Subject: draft-ietf-ldapext-ldap-java-api-07 changes since draft 06

From: "Steve Sonntag" <[email-masked]>
Date: Wed, 06 Oct 1999 15:53:47 -0600

just a minor nit

Appendix B - changes from draft-ietf-ldapext-ldap-java-api-06.txt
should include the following:

11.1 LDAPAttributeSchema
Change 
   Added getSuperior() (5.2.4) and getSyntaxString() (5.2.3).
to   Added getSuperior() (5.2.4), getSyntaxString() (5.2.3), and getAliases() (5.2.5).

------------------------
Steve Sonntag
Novell Directory Services
+1 801 861 7097

---

From: [email-masked] (Rob Weltman)
Date: Wed, 06 Oct 1999 17:25:39 -0700

> to   Added getSuperior() (5.2.4), getSyntaxString() (5.2.3), and getAliases() (5.2.5).

  Actually, the appendix is right, item 5.2.5 is wrong: getAliases() is declared in LDAPSchemaElement, which LDAPAttributeSchema extends, so it shouldn't have been declared in LDAPAttributeSchema :-(

Rob

---

From: [email-masked] (Rob Weltman)
Date: Sun, 17 Oct 1999 18:39:09 -0700

OK, I've now reviewed all the comments to the draft from Steve. I'm also attaching a draft that takes them into account. They are mostly editorial changes that do not affect the API, the exceptions being:

- Removed all references to syntax as an enumerated type. It is only referred to as a String (an OID) now.

- Added LDAPConnection.getAuthenticationMethod().

Thanks,
Rob

> to Added getSuperior() (5.2.4), getSyntaxString() (5.2.3), and getAliases() (5.2.5).

  getAliases() should not be added. It's a method of LDAPSchemaElement (which LDAPAttributeSchema extends), and should not be listed under LDAPAttributeSchema.

> 5.1.13 removeValue
>
> I believe the correct prototype for the removeValue method that operates on a byte[] formated value should be
>
>      public synchronized void removeValue(byte attrBytes[])
>
>                   instead of
>
>      public synchronized void removeValue(byte attrValue[])
>
> so that it matches the parameters that follow.
>

  OK

> I have some questions about the abstract class LDAPSchemaElement
>
> I had some difficulty understanding what is meant by "qualifiers" in the description of the getQualifier and setQualifier methods.  RFC 2252 is referenced, but it makes no mention of qualifiers.   If I am not mistaken qualifiers in this draft are the same as "terms" in RFC 2252 (4.2, 4.3.3, 4.4, 4.5).  To help others who might have the same problem, may I suggest alternative wording.
>
> 5.22.1 getAliases   public String[] getAliases()   Returns an array of all values except for the first value of the NAME qualifier, or null if there are none.
>
> 5.22.2 getDescription   public String getDescription()   Returns the value of the DESC qualifier.
>
> 5.22.3 getName   public String getName()   Returns the first value of the NAME qualifier.
> and so on ...
>
> GetQualifier now left unchanged, adding only a parameters section, viz:
>
> 5.22.5 getQualifier   public String[] getQualifier(String name)   Returns an array of all values of a specified optional or non-   standard qualifier of the element. This method may be used to access   the values of vendor-specific qualifiers (which begin with "X-" [2]).
>    Parameters are:
>
>        name                 The name of the qualifier  Q. Is it case insensitive or must the name be all
>                                  upper case as listed in RFC 2252?  If a vendor specific qualifier,
>                                  must the name match the case of names returned in getQualifierNames()?
>
> and the same goes for setQualifier:
>
> 5.22.9 setQualifier   public void setQualifier(String name, String[] values)   Sets the values of a specified optional or non-standard qualifier of   the element. This method may be used to set the values of vendor-   specific qualifiers (which begin with "X-" [2]).
>
>   Parameters are:
>
>        name                 The name of the qualifier.
>
>        values                The values to set for the qualifier.
>

  I'll add something close to the suggested text, but I don't want to remove the existing text. The proposed text above only makes sense if the reader has RFC 2252 in front of him, or has the syntax of LDAP schema definitions vividly in memory. The draft doesn't define or present that syntax, since the API abstracts from it.

> I am having trouble inderstanding modify method (5.22.12) in the abstract class LDAPSchemaElement.
>
> The text from the draft with my questions follow:
>
> > 5.22.12 modify> >    public void modify(LDAPConnection ld>                       LDAPAttributeSchema newValue) throws LDAPException>
> Why are we passing the parameter newValue as a LDAPAttributeSchema type.  LDAPAttributeSchema is a class that implements class LDAPSchemaElement (this class).  Should this parameter be type LDAPSchemaElement?
>

  Yes. That's a typo.

> >    public void modify(LDAPConnection ld>                       LDAPAttributeSchema newValue,>                       String dn) throws LDAPException> >    Replace a single value of the schema element definition in the>    schema. An exception is thrown if the definition can't be modified.>
> I don't understand what the modify call does.  Are we changing the value of single a qualifier here or something else?  If sq qualifier, how is it determined which one is changed?  If using LDAPSchemaElement as the parameter, are all qualifiers with values in the class designated by "newValue" used to change to the designated LDAPSchemaElement?  Only the non-standard qualifiers can be set to a value using setQualifier() so this would modify only not-standard qualifiers.  Enough rambling - I'm lost on this one.
>

  The entire schema definition of the "this" object is replaced with the definition passed in as a parameter. Think of it as deleting the previous definition and adding a new one.

> >    Parameters are:> >       ld             An open connection to a Directory Server.>                       Typically the connection must have been>                       authenticated to modify a schema definition.> >       newValue       The new schema element value.> >       dn             Entry at which to determine the SubschemaSubentry>                       to store the schema change in.
>

> from the .07 draft
>
> > 5.2.2 getSyntax (class LDAPAttributeSchema)
> > Returns the type of the attribute - one of cis, ces, binary, int,telephone, or dn.
> > 5.14.3 getSyntax (class LDAPMatchingRuleSchema)
> > Returns the type of the matching rule - one of cis, ces, binary, int, telephone, or dn.
>
> Should these really say something like
>
> Returns the syntax of the xxxx as defined in [2]
>

  As discussed in another thread on this list, those methods and any anything else referring to "cis", "ces", etc or to treating syntaxes as enumerated integers will be deleted from the draft. They refer to a particular LDAP implementation (that of UMich and many derived servers) and are not relevant to other implementations. The functionality they represent was already provided in the draft with methods of the form that return the well-known OID:

public String getSyntaxString()

> From draft-...-api-07
>
> > 5.6.5 getAuthenticationPassword> >    public String getAuthenticationPassword()> >    Returns the password
> used for simple authentication by this object.>   null is returned if no authentication has been performed.
>
> Should there be a behavior defined when authentication is not simple?
>
>

  This was discussed briefly earlier on the LDAPEXT list. I think null is appropriate when authentication is not simple. However, it would be useful to add an API to determine what authentication method was used. How about this:

public String getAuthenticationMethod()

Returns the authentication method used by the connection: "none", "simple", or "sasl" are the currently defined methods.

> Editorial question.  Should classes that come from the Java jdk be designated by
> their fully qualified names instead of their simple names.  This makes the draft
> more exact and in some cases where multiple instances of a class by that name
> exist, defines explicitly which class is referenced (even though it may seem
> obvious).
>
> Example:
>
> public String getAuthenticationDN()
>          replace with
> public java.lang.String getAuthenticationDN()
>
> public InputStream getInputStream()
>          replace with
> public java.io.InputStream getInputStream()
>         (It is NOT org.omg.CORBA.portable.InputStream)
>

  I'm not strongly opposed to that, but it seems unnecessary in this draft. All locally defined classes start with LDAP, so they are clearly distinguished from Java base classes or imported packages. With one exception, there are no dependencies on any packages other than the Java base classes, so there is no risk of inferring that InputStream refers to CORBA rather than to java.io. The single exception is the reference in the SASL methods to the Callback and CallbackHandler interfaces from javax.security.auth.callback, and those two are already clearly declared as javax.security.auth.callback.CallbackHandler and javax.security.auth.callback.Callback.

> 5.6.17
>
> Does search (static method) create a new connection automatically and then
> disconnect after the completion of the search similar to LDAPConnection.read?
>

  Yes. search() and read() are really the same in an LDAP implementation - it's just the scope that differs. I'll copy the text from read() to the section on search().

> minor editoral comment
>
> 5.6.22
>
> >> Sets the constraints that apply to all searchoperations performed
> missing a space
>

  OK

> minor typo
>
> 5.7.10 setReferrals
>
> Referrals of any type other to an LDAP server
>
>          probably should read
>
> Referrals of any type other than to an LDAP server
>

  OK

> Editorial Comment
>
> Section 5.10.2 Attribute
>
> It references section 5.2.4 for syntax and semantics,  but this makes
> no sense.  What should the reference  be?  Maybe 5.3.5?
>

  Yes.

> Editorial question
>
> I was wondering why methods "getID()" and "getOID" are used to
> perform the same kind of function.
>
> 5.8.3 - LDAPControl uses getID
> 5.11.2 - LDAPExtendedOperation useds getID
> 5.22.4 - LDAPSchemaElement uses getOID
>
> Should the naming be consistent?
>

  Yes. To minimize the total number of changes, I'll make getID() be the name used throughout.

> LDAPAttributeSchema (5.2) has a method to support  legacy code
>      getSyntax
> which supports syntaxes cis, ces, etc., and
>      getSyntaxString
> for support of all syntaxes.
>
> Shouldn't there be something similar for class LDAPMatchingRuleSchema
> (5.14) which has the method
>       getSyntax
> which supports cis, ces, etc. but has no method for support of all syntaxes.
>

  See the earlier discussion of getSyntax(). The method will be removed.

> Editorial Comment
>
> (5,22,11)
> for the remove function, should the comments on the "dn" parameter discuss remove
> instead of store?
>
> > dn             Entry at which to determine the SubschemaSubentry>                       to store the schema
> change in.
>
> Does the same comment apply to modify?
>

  Yes

> Should definitions for
>       cis, ces, binary, int, telephone, or dn
> be specified in LDAPAttributeSchema so that there is consistency
> between implementations?
>
  All references to these constants will be removed, as discussed earlier.

> In  RFCs 2252 ABSTRACT, STRUCTURAL, and AUXILIARY are specifeid as strings when
> creating a new schema definition.
>
> The java-07 draft specifies in 5.17.1 that these are constants defined in
> LDAPObjectClassSchema.  Since these are defined only here as integers, shouldn't
> the value of these integer constants be defined to ensure interoperability.
>

  I don't believe their values are relevant to a user of the API, but only to the internal implementation. They may differ between implementations.

> In most instances for each method that has arguments, there is section following
> that describes the meaning of the argument.  In a few cases this is not the case.
> I thought that for seemingly trivial cases arguments sometimes aren't defined, but
> for most trivial cases they are defined.  Some missing arguments are not trivial.
>
> Shouldn't a separate explaination be given for each argument for clarity and
> completness?
>
> examples where missing:
>
> 5.22.9 setQualifier
> 5.22.5 getQualifier
> 5.21.3 getAttribute
> 5.18.1 LDAPRebindAuth
>
> etc.
>

  Yes

>         LDAPSchema.fetchschema()
>
> Shouldn't the draft give some indication why an exception is thrown for this
> method.
>

  OK:

An LDAPException is thrown as for LDAPConnection.search() (5.28.11) if the schema cannot be retrieved with the specified connection.

> I would also like to see a sentence telling the behavior of the constructor for
> this class (LDAPSchema).
>

OK:

Constructs an empty LDAPSchema object.

> Shouldn't the getObjectClasss and getMatchingRule methods each have
> a String parameter so that the application can specify which "patricular"
> definition to get?
>
> i.e.
> 5.21.4
> public LDAPObjectClassSchema getObjectClass(String name)
>   and
> 5.21.5
> public LDAPMatchingRuleSchema getMatchingRule(String name)
>

  Yes, that was a typo.

> Picky Editorial Comment
>
> 5.23.1
>
> Minor typo in the constructor parameter serverTimeLimit
>
> Needs  space(s) between serverTimeLimit and the start of the description.
>
> serverTimeLimitMaximum time in seconds that the server should
> spend returning results. This is a server-imposed                      limit.
>

  OK (it's an artifact of Word's generic text formatting).

> 5.24.5
> Since java.Enumeration.nextElement throws java.util.NoSuchElementException
> LDAPSearchResults.nextElement should throw that exception as well.
>

  Runtime exceptions (i.e. ones not requiring a throws clause) are typically not listed. In this case, also, the behavior is that of the interface (by necessity), so it is not necessary to list it.

> LDAPUrl constructor
>
> It would sound better if the description of the second constructor is changed as
> follows:
>
> Constructs with the specified host ...
>      to
> Constructs a URL object with the specified host
>

OK

> LDAPUrl constructors / dn param
>
> 5.27.1
>
> The description of the dn parameter makes it sound like an object is
> being fetched, when the just the name is being fetched.
>
> Maybe the wording could be changed as follows:
>
>
>
> dn             Distinguished name of object to fetch.
>
>        to
>
> dn             Distinguished objecct name to fetch.
>

  This is a parameter to the constructor, telling it which object to fetch (i.e. it is an IN parameter, not an OUT parameter). No need to fetch the DN, since the caller is providing it.

> The description of attrNames makes it seem that attributes are being fetched.  I
> think only names are fetched.  Perhaps better wording would be:
>
> Names of attributes to retrieve. null for all attributes.
>            to
> Attribute names to retrieve. null for all attribute names.
>

  Same as for DN

> 5.27.1
> What happens on constructor 2 or 3 if the object doesn't exist in the named
> direcctory.  Is some exception thrown or is an emply filter returned?  The API
> makes it sound like the API actually goes to the directory to "fetch" information -
> or does it really just build a URL in the interface based on the information
> supplied?
>
> Does the same reasoning apply to the attributes as well.  If it fetches from the
> directory, what happens if the names attributes don't exist?
>

  The latter. The description says:

"Constructs a full-blown LDAP URL to specify an LDAP search operation."

  There are then explicit operations to use the URL to execute a search operation.

Network Working Group                                        Rob Weltman
INTERNET-DRAFT                             Netscape Communications Corp.
                                                     Christine Tomlinson
                                            Innosoft International, Inc.
                                                              Mark Smith
                                           Netscape Communications Corp.
                                                               Tim Howes
                                                         October 8, 1999

               The Java LDAP Application Program Interface
                  draft-ietf-ldapext-ldap-java-api-07.txt

Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Task Force
   (IETF), its areas, and its working groups.  Note that other groups
   may also distribute working documents as Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

Abstract

   This document defines a java language application program interface
   to the lightweight directory access protocol (LDAP), in the form of a
   class library. It complements but does not replace RFC 1823 ([8]),
   which describes a C language application program interface. It
   updates and the previous draft in correcting a few minor errors which
   are listed in appendix B.

   The companion document draft-ietf-ldapext-ldap-java-api-asynch-ext-
   01.txt [11] defines the mandatory to implement asynchronous layer of
   the API.

Expires April 8, 2000                                         [Page 1]

JAVA LDAP API                                             October 1999

1.   Introduction.....................................................8
2.   Overview of the LDAP model.......................................8
3.   Overview of the LDAP classes.....................................9
3.1  Interfaces.......................................................9
3.2  Classes.........................................................10
3.3  Exceptions......................................................12
4.   Overview of LDAP API use........................................12
5.   The java LDAP classes...........................................13
5.1  public class LDAPAttribute......................................13
5.1.1   Constructors.................................................13
5.1.2   addValue.....................................................14
5.1.3   getByteValues................................................14
5.1.4   getStringValues..............................................14
5.1.5   getByteValueArray............................................15
5.1.6   getStringValueArray..........................................15
5.1.7   getLangSubtype...............................................15
5.1.8   getBaseName..................................................15
5.1.9   getName......................................................15
5.1.10  getSubtypes..................................................15
5.1.11  hasSubtype...................................................16
5.1.12  hasSubtypes..................................................16
5.1.13  removeValue..................................................16
5.1.14  size.........................................................17
5.2  public class LDAPAttributeSchema................................17
5.2.1   Constructors.................................................17
5.2.2   getSyntaxString..............................................18
5.2.3   getSuperior..................................................18
5.2.4   isSingleValued...............................................18
5.3  public class LDAPAttributeSet...................................18
5.3.1   Constructors.................................................18
5.3.2   add..........................................................19
5.3.3   clone........................................................19
5.3.4   elementAt....................................................19
5.3.5   getAttribute.................................................19
5.3.6   getAttributes................................................20
5.3.7   getSubset....................................................21
5.3.8   remove.......................................................21
5.3.9   removeElementAt..............................................21
5.3.10  size.........................................................22
5.4  public interface LDAPBind.......................................22
5.4.1   bind.........................................................22
5.5  public class LDAPCompareAttrNames...............................22
5.5.1   Constructors.................................................22
5.5.2   getLocale....................................................23
5.5.3   setLocale....................................................24
5.5.4   isGreater....................................................24
5.6  public class LDAPConnection.....................................24
5.6.1   Constructors.................................................24
5.6.2   clone........................................................25
5.6.3   finalize.....................................................25
5.6.4   getAuthenticationDN..........................................25

Expires April 8, 2000                                         [Page 2]

JAVA LDAP API                                             October 1999

5.6.5   getAuthenticationMethod......................................25
5.6.6   getAuthenticationPassword....................................26
5.6.7   getHost......................................................26
5.6.8   getInputStream...............................................26
5.6.9   getOutputStream..............................................26
5.6.10  getPort......................................................26
5.6.11  getProperty..................................................27
5.6.12  getConstraints...............................................27
5.6.13  getSearchConstraints.........................................28
5.6.14  getSocketFactory.............................................28
5.6.15  isBound......................................................28
5.6.16  isConnected..................................................28
5.6.17  read.........................................................28
5.6.18  search.......................................................29
5.6.19  setConstraints...............................................29
5.6.20  setInputStream...............................................30
5.6.21  setOutputStream..............................................30
5.6.22  setProperty..................................................30
5.6.23  setSearchConstraints.........................................30
5.6.24  setSocketFactory.............................................31
5.7  public class LDAPConstraints....................................31
5.7.1   Constructors.................................................31
5.7.2   getHopLimit..................................................32
5.7.3   getBindProc..................................................33
5.7.4   getRebindProc................................................33
5.7.5   getReferrals.................................................33
5.7.6   getTimeLimit.................................................33
5.7.7   setHopLimit..................................................33
5.7.8   setBindProc..................................................34
5.7.9   setRebindProc................................................34
5.7.10  setReferrals.................................................34
5.7.11  setTimeLimit.................................................34
5.7.12  getClientControls............................................35
5.7.13  getServerControls............................................35
5.7.14  setClientControls............................................35
5.7.15  setServerControls............................................35
5.8  public class LDAPControl........................................35
5.8.1   Constructors.................................................36
5.8.2   clone........................................................36
5.8.3   getID........................................................36
5.8.4   getValue.....................................................36
5.8.5   isCritical...................................................36
5.8.6   newInstance..................................................37
5.8.7   register.....................................................37
5.9  public class LDAPDN.............................................37
5.9.1   equals.......................................................37
5.9.2   escapeRDN....................................................37
5.9.3   unescapeRDN..................................................38
5.9.4   explodeDN....................................................38
5.9.5   explodeRDN...................................................38
5.10 public class LDAPEntry..........................................39
5.10.1  Constructors.................................................39

Expires April 8, 2000                                         [Page 3]

JAVA LDAP API                                             October 1999

5.10.2  getAttribute.................................................39
5.10.3  getAttributeSet..............................................40
5.10.4  getDN........................................................40
5.11 public class LDAPExtendedOperation..............................40
5.11.1  Constructors.................................................40
5.11.2  getID........................................................41
5.11.3  getValue.....................................................41
5.12 public interface LDAPEntryComparator............................41
5.12.1  isGreater....................................................41
5.13 public class LDAPException......................................41
5.13.1  Constructors.................................................42
5.13.2  errorCodeToString............................................42
5.13.3  getLDAPErrorMessage..........................................43
5.13.4  getLDAPResultCode............................................43
5.13.5  getMatchedDN.................................................43
5.13.6  Error codes..................................................43
5.14 public class LDAPMatchingRuleSchema.............................45
5.14.1  Constructors.................................................45
5.14.2  getAttributes................................................46
5.15 public class LDAPModification...................................46
5.15.1  Constructors.................................................46
5.15.2  getAttribute.................................................47
5.15.3  getOp........................................................47
5.16 public class LDAPModificationSet................................47
5.16.1  Constructors.................................................47
5.16.2  add..........................................................47
5.16.3  elementAt....................................................47
5.16.4  remove.......................................................48
5.16.5  removeElementAt..............................................48
5.16.6  size.........................................................48
5.17 public class LDAPObjectClassSchema..............................48
5.17.1  Constructors.................................................48
5.17.2  getSuperiors.................................................49
5.17.3  getRequiredAttributes........................................49
5.17.4  getOptionalAttributes........................................50
5.17.5  getType......................................................50
5.18 public class LDAPRebindAuth.....................................50
5.18.1  Constructors.................................................50
5.18.2  getDN........................................................50
5.18.3  getPassword..................................................50
5.19 public interface LDAPRebind.....................................51
5.19.1  getRebindAuthentication......................................51
5.20 public class LDAPReferralException..............................51
5.20.1  Constructors.................................................51
5.20.2  getURLs......................................................52
5.21 public class LDAPSchema.........................................52
5.21.1  Constructors.................................................52
5.21.2  fetchSchema..................................................52
5.21.3  getAttribute.................................................53
5.21.4  getObjectClass...............................................53
5.21.5  getMatchingRule..............................................53
5.21.6  getAttributes................................................53

Expires April 8, 2000                                         [Page 4]

JAVA LDAP API                                             October 1999

5.21.7  getObjectClasses.............................................54
5.21.8  getMatchingRules.............................................54
5.21.9  getAttributeNames............................................54
5.21.10  getObjectClassNames.........................................54
5.21.11  getMatchingRuleNames........................................54
5.22 public abstract class LDAPSchemaElement.........................54
5.22.1  getAliases...................................................54
5.22.2  getDescription...............................................55
5.22.3  getName......................................................55
5.22.4  getID........................................................55
5.22.5  getQualifier.................................................55
5.22.6  getQualifierNames............................................55
5.22.7  isObsolete...................................................55
5.22.8  getValue.....................................................56
5.22.9  setQualifier.................................................56
5.22.10  add.........................................................56
5.22.11  remove......................................................56
5.22.12  modify......................................................57
5.23 public class LDAPSearchConstraints extends LDAPConstraints......57
5.23.1  Constructors.................................................57
5.23.2  getBatchSize.................................................59
5.23.3  getDereference...............................................59
5.23.4  getMaxResults................................................59
5.23.5  getServerTimeLimit...........................................59
5.23.6  setBatchSize.................................................60
5.23.7  setDereference...............................................60
5.23.8  setMaxResults................................................60
5.23.9  setServerTimeLimit...........................................60
5.24 public class LDAPSearchResults..................................60
5.24.1  getCount.....................................................61
5.24.2  getResponseControls..........................................61
5.24.3  hasMoreElements..............................................61
5.24.4  next.........................................................61
5.24.5  nextElement..................................................61
5.24.6  sort.........................................................62
5.25 public interface LDAPSocketFactory..............................62
5.25.1  makeSocket...................................................62
5.26 public class LDAPSortKey........................................63
5.26.1  Constructors.................................................63
5.26.2  getKey.......................................................64
5.26.3  getReverse...................................................64
5.26.4  getMatchRule.................................................64
5.27 public class LDAPUrl............................................64
5.27.1  Constructors.................................................64
5.27.2  decode.......................................................65
5.27.3  encode.......................................................65
5.27.4  getAttributes................................................66
5.27.5  getAttributes................................................66
5.27.6  getDN........................................................66
5.27.7  getFilter....................................................66
5.27.8  getHost......................................................66
5.27.9  getPort......................................................66

Expires April 8, 2000                                         [Page 5]

JAVA LDAP API                                             October 1999

5.27.10  getUrl......................................................66
5.28 public interface LDAPv2.........................................67
5.28.1  abandon......................................................67
5.28.2  bind.........................................................67
5.28.3  compare......................................................68
5.28.4  connect......................................................68
5.28.5  delete.......................................................69
5.28.6  disconnect...................................................70
5.28.7  getOption....................................................70
5.28.8  modify.......................................................70
5.28.9  read.........................................................71
5.28.10  rename......................................................72
5.28.11  search......................................................72
5.28.12  setOption...................................................74
5.29 public interface LDAPv3.........................................78
5.29.1  bind.........................................................78
5.29.2  connect......................................................79
5.29.3  extendedOperation............................................80
5.29.4  getResponseControls..........................................81
5.29.5  rename.......................................................81
5.30 Client and Server Controls......................................82
6.   Security Considerations.........................................82
7.   Acknowledgements................................................82
8.   Bibliography....................................................83
9.   Authors' Addresses..............................................83
10.  Appendix A - Sample java LDAP programs..........................85
11.  Appendix B - Changes from draft-ietf-ldapext-ldap-java-api-07.txt89
11.1 LDAPAttributeSchema.............................................89
11.2 LDAPConnection..................................................89
12.  Appendix C - Changes from draft-ietf-ldapext-ldap-java-api-06.txt89
12.1 LDAPAttributeSchema.............................................89
12.2 LDAPConnection..................................................89
12.3 LDAPDN..........................................................89
12.4 LDAPException...................................................90
12.5 LDAPMatchingRuleSchema..........................................90
12.6 LDAPObjectClassSchema...........................................90
12.7 LDAPSchemaElement...............................................90
13.  Appendix D - Changes from draft-ietf-ldapext-ldap-java-api-05.txt90
13.1 LDAPConnection..................................................90
13.2 LDAPConstraints.................................................90
13.3 LDAPSearchConstraints...........................................90
13.4 LDAPControl.....................................................91
13.5 LDAPv3..........................................................91
14.  Appendix D - Changes from draft-ietf-ldapext-ldap-java-api-04.txt91
14.1 LDAPAttribute...................................................91
14.2 LDAPCompareAttrNames............................................91
14.3 LDAPSchemaElement...............................................91
14.4 LDAPSchemaElement...............................................91
15.  Appendix E - Changes from draft-ietf-ldapext-ldap-java-api-03.txt91
15.1 LDAPBind........................................................91
15.2 LDAPControl.....................................................91
15.3 LDAPConstraints.................................................91

Expires April 8, 2000                                         [Page 6]

JAVA LDAP API                                             October 1999

15.4 LDAPRebind......................................................92
15.5 LDAPRebindProc..................................................92
15.6 LDAPSearchConstraints...........................................92
15.7 LDAPSearchResults...............................................92
15.8 LDAPv2..........................................................92
15.9 LDAPv3..........................................................92
16.  Appendix F - Changes from draft-ietf-ldapext-ldap-java-api-02.txt92
16.1 LDAPSearchConstraints...........................................92
16.2 LDAPRebind......................................................92
16.3 LDAPRebindProc..................................................93
17.  Appendix F - Changes from draft-ietf-ldapext-ldap-java-api-01.txt93
17.1 LDAPAttribute...................................................93
17.2 LDAPAttributeSet................................................93
17.3 LDAPDN..........................................................93
17.4 LDAPException...................................................93
17.5 LDAPSearchResults...............................................93
17.6 LDAPConnection..................................................93
17.7 LDAPv2..........................................................93
17.8 LDAPv3..........................................................93

Expires April 8, 2000                                         [Page 7]

JAVA LDAP API                                             October 1999

1. Introduction

   The LDAP class library is designed to provide powerful, yet simple,
   access to a LDAP directory services.  It defines a synchronous
   interface to LDAP, with support for partial results on searching, to
   suit a wide variety of applications. This document gives a brief
   overview of the LDAP model, then an overview of the constituents of
   the class library.
   The public class methods are described in detail, followed by an
   appendix that provides some example code demonstrating the use of the
   classes, and an appendix listing changes from earlier drafts.

2. Overview of the LDAP model

   LDAP is the lightweight directory access protocol, described in [2]
   and [6]. It defines a lightweight access mechanism in which clients
   send requests to and receive responses from LDAP servers.

   The LDAP information model comes from X.500 [1] and is based on the
   entry, which contains information about some object (e.g., a person).
   Entries are composed of attributes, which have a type and one or more
   values. Each attribute has a syntax that determines what kinds of
   values are allowed in the attribute (e.g., ASCII characters, a jpeg
   photograph, etc.) and how those values behave during directory
   operations (e.g., is case significant during comparisons).

   Entries may be organized in a tree structure, usually based on
   political, geographical, and organizational boundaries. Other
   structures are possible, including a flat namespace. Each entry is
   uniquely named relative to its sibling entries by its relative
   distinguished name (RDN) consisting of one or more distinguished
   attribute values from the entry. At most one value from each
   attribute may be used in the RDN. For example, the entry for the
   person Babs Jensen might be named with the "Barbara Jensen" value
   from the commonName attribute.

   A globally unique name for an entry, called a distinguished name or
   DN, is constructed by concatenating the sequence of RDNs from the
   entry up to the root of the tree. For example, if Babs worked for the
   University of Michigan, the DN of her U-M entry might be "cn=Barbara
   Jensen, o=University of Michigan, c=US". The DN format used by LDAP
   is defined in [4].

   Operations are provided to authenticate, search for and retrieve
   information, modify information, and add and delete entries from the
   tree.

   An LDAP server may return referrals if it cannot completely service a
   request (for example if the request specifies a directory base
   outside of the tree managed by the server). The LDAP class library

Expires April 8, 2000                                         [Page 8]

JAVA LDAP API                                             October 1999

   offers the programmer two options: the programmer can catch these
   referrals as exceptions and explicitly issue new requests to the
   referred-to servers, or the programmer can let the library
   automatically follow the referrals.  In the latter case, the
   programmer may also provide a reauthentication object, allowing
   automatic referrals to proceed with appropriate credentials (as
   opposed to anonymous authentication) for each referred to server.

   Before the client encodes and sends a string value to a server, the
   string values are converted from the java 16-bit Unicode format to
   UTF-8 format. Then, when the values are received by the server, the
   values are converted back to 16-bit Unicodeformat.  The integrity of
   double-byte and other non-ASCII character sets is fully preserved.

   The next sections give an overview of how the class library is used
   and detailed descriptions of the LDAP class methods that implement
   all of these functions.

3.  Overview of the LDAP classes

   The central LDAP class is LDAPConnection. It provides methods to
   establish an authenticated or anonymous connection to an LDAP server,
   as well as methods to search for, modify, compare, and delete entries
   in the directory.

   The LDAPConnection class also provides fields for storing settings
   that are specific to the LDAP session (such as limits on the number
   of results returned or timeout limits). An LDAPConnection object can
   be cloned, allowing objects to share a single network connection but
   use different settings (using LDAPConnection.setOption()).

   To support extensions of the LDAP protocol LDAPConnection and to add
   the capability to determine the LDAP protocol level supported by an
   LDAPConnection object, LDAPConnection implements a protocol
   interface, which is currently LDAPv3.

   A search conducted by an LDAPConnection object returns results in an
   LDAPSearchResults object, which can be enumerated to access the
   entries found. Each entry (represented by an LDAPEntry object)
   provides access to the attributes (represented by LDAPAttribute
   objects) returned for that entry. Each attribute can produce the
   values found as byte arrays or as Strings.

3.1 Interfaces

   LDAPEntryComparator    An interface to support arbitrary sorting
                          algorithms for entries returned by a search
                          operation. The basic java LDAP classes
                          include one implementation:

Expires April 8, 2000                                         [Page 9]

JAVA LDAP API                                             October 1999

                          LDAPCompareAttrNames, to sort in ascending
                          order based on one or more attribute names.

   LDAPRebind             A programmer desiring reauthentication on
                          automatically following referrals must
                          implement this interface. Without it,
                          automatically followed referrals will use
                          anonymous authentication. Referrals of any
                          type other than to an LDAP server (i.e. a
                          referral URL other than ldap://something) are
                          ignored on automatic referral following.

   LDAPBind               This interface allows a programmer to
                          override the default authentication and
                          reauthentication (on referral following)
                          behavior of a connection. It is typically
                          used to control the authentication mechanism
                          used on implicit referral handling.

   LDAPSocketFactory      Programmers needing to provide or use
                          specialized socket connections, including
                          Transport Layer Security (TLS) based ones,
                          can provide an object constructor to
                          implement them using this interface.

   LDAPv2                 This interface defines the functionality of
                          the LDAP version 2 protocol. It is
                          implemented by LDAPConnection.

   LDAPv3                 This interface extends LDAPv2, adding the
                          functionality of the LDAP version 3 protocol.
                          It is implemented by LDAPConnection.

3.2 Classes

   LDAPAttribute          Represents the name and values of one
                          attribute of a directory entry.

   LDAPAttributeSchema    Represents the schematic definition of a
                          particular attribute in a particular
                          Directory Server.

   LDAPAttributeSet       A collection of LDAPAttributes.

Expires April 8, 2000                                        [Page 10]

JAVA LDAP API                                             October 1999

   LDAPCompareAttrNames   An implementation of LDAPEntryComparator, to
                          support sorting of search results by one or
                          more attributes.

   LDAPConnection         Implements LDAPv3 and is the central point
                          for interactions with a directory.

   LDAPConstraints        Defines options controlling all operations.

   LDAPControl            Sets additional parameters or constraints for
                          an LDAP operation, either on the server or on
                          the client.

   LDAPDN                 A utility class to facilitate composition and
                          decomposition of distinguished names (DNs).

   LDAPEntry              Represents a single entry in a directory.

   LDAPExtendedOperation  Encapsulates the ID and data associated with
                          the sending or receiving of an extended
                          operation (an LDAPv3 feature).

   LDAPMatchingRuleSchema Represents the schematic definition of a
                          particular matching rule in a particular
                          Directory Server.

   LDAPModification       A single add/delete/replace operation to an
                          LDAPAttribute.

   LDAPModificationSet    A collection of LDAPModifications.

   LDAPObjectClassSchema  Represents the schematic definition of a
                          particular object class in a particular
                          Directory Server.

   LDAPRebindAuth         An implementation of LDAPRebind must be able
                          to provide an LDAPRebindAuth at the time of a
                          referral. The class encapsulates
                          reauthentication credentials.

Expires April 8, 2000                                        [Page 11]

JAVA LDAP API                                             October 1999

   LDAPSchema             Represents the schema of a particular
                          Directory Server.

   LDAPSchemaElement      Base class for representing LDAP schema
                          elements.

   LDAPSearchConstraints  Defines the options controlling search
                          operations.

   LDAPSearchResults      The enumerable results of a search operation.

   LDAPSortKey            Specifies how search results are to be
                          sorted.

   LDAPUrl                Encapsulates parameters of an LDAP Url query,
                          as defined in [7].

3.3 Exceptions

   LDAPException         General exception, which includes an error
                         message and an LDAP error code.

   LDAPReferralException Derived from LDAPException and contains a list
                         of LDAPUrls corresponding to referrals received
                         on an LDAP operation.

4. Overview of LDAP API use

   An application generally uses the LDAP API in four steps.

   -    Construct an LDAPConnection.  Initialize an LDAP session with a
        directory server. The LDAPConnection.connect() call establishes
        a handle to the session, allowing multiple sessions to be open
        at once, on different instances of LDAPConnection.

   -    Authenticate to the LDAP server with LDAPConnection.bind().

   -    Perform some LDAP operations and obtain some results.
        LDAPConnection.search() returns an LDAPSearchResults, which can
        be enumerated to access all entries found.
        LDAPConnection.read() returns a single entry.

Expires April 8, 2000                                        [Page 12]

JAVA LDAP API                                             October 1999

   -    Close the connection. The LDAPConnection.disconnect() call
        closes the connection.

   All operations described in this draft are synchronous - they do not
   return until the operation has completed. To facilitate user feedback
   during searches, intermediate search results can be obtained before
   the entire search operation is completed by specifying the number of
   entries to return at a time. The companion document draft-ietf-
   ldapext-ldap-java-api-asynch-ext-02.txt [19] defines low-level
   asynchronous versions of the LDAP operation methods.

   Standard java Enumerations are used to parse search results. Errors
   result in the throwing of an LDAPException, with a specific error
   code and context-specific textual information available.

   The following sections describe the LDAP classes in more detail.

5. The java LDAP classes

5.1 public class LDAPAttribute

   The LDAPAttribute class represents the name and values of an
   attribute. It is used to specify an attribute to be added to, deleted
   from, or modified in a Directory entry. It is also returned on a
   search of a Directory.

5.1.1 Constructors

   public LDAPAttribute(LDAPAttribute attr)

   Constructs an attribute with copies of all values of the input
   attribute.

   public LDAPAttribute(String attrName)

   Constructs an attribute with no values.

   public LDAPAttribute(String attrName,
                           byte attrBytes[])

   Constructs an attribute with a byte-formatted value.

   public LDAPAttribute(String attrName,
                           String attrString)

Expires April 8, 2000                                        [Page 13]

JAVA LDAP API                                             October 1999

   Constructs an attribute that has a single string value.

   public LDAPAttribute(String attrName,
                        String attrStrings[])

   Constructs an attribute that has an array of string values.

   Parameters are:

      attr           An attribute to use as template.

      attrName       Name of the attribute.

      attrBytes      Value of the attribute as raw bytes.

      attrString     Value of the attribute as a String.

      attrStrings    Array of values as Strings.

      attrBytesArray Array of values as raw byte arrays.

5.1.2 addValue

   public synchronized void addValue(String attrString)

   Adds a string value to the attribute.

   public synchronized void addValue(byte attrBytes[])

   Adds a byte[]-formatted value to the attribute.

   Parameters are:

      attrString     Value of the attribute as a String.

      attrBytes      Value of the attribute as raw bytes.

5.1.3 getByteValues

   public Enumeration getByteValues()

   Returns an enumerator for the values of the attribute in byte[]
   format.

5.1.4 getStringValues

Expires April 8, 2000                                        [Page 14]

JAVA LDAP API                                             October 1999

   public Enumeration getStringValues()

   Returns an enumerator for the string values of an attribute.

5.1.5 getByteValueArray

   public byte[][] getByteValueArray()

   Returns the values of the attribute as an array of byte[].

5.1.6 getStringValueArray

   public String[] getStringValueArray()

   Returns the values of the attribute as an array of Strings.

5.1.7 getLangSubtype

   public String getLangSubtype()

   Returns the language subtype, if any. For example, if the attribute
   name is cn;lang-ja;phonetic, this method returns the String lang-ja.

5.1.8 getBaseName

   public String getBaseName()

   public static String getBaseName(String attrName)

   Returns the base name. For example, if the attribute name is cn;lang-
   ja;phonetic, this method returns cn.

      attrName       Name of the attribute to extract the base name
                      from.

5.1.9 getName

   public String getName()

   Returns the name of the attribute.

5.1.10 getSubtypes

   public String[] getSubtypes()

   public static String[] getSubtypes(String attrName)

Expires April 8, 2000                                        [Page 15]

JAVA LDAP API                                             October 1999

   Extracts the subtypes from the specified attribute name. For example,
   if the attribute name is cn;lang-ja;phonetic, this method returns an
   array containing lang-ja and phonetic.

   Parameters are:

      attrName       Name of the attribute to extract the subtypes
                      from.

5.1.11 hasSubtype

   public boolean hasSubtype(String subtype)

   Reports if the attribute name contains the specified subtype. For
   example, if you check for the subtype lang-en and the attribute name
   is cn;lang-en, this method returns true.

   Parameters are:

      subtype        The single subtype to check for.

5.1.12 hasSubtypes

   public boolean hasSubtypes(String[] subtypes)

   Reports if the attribute name contains all specified subtypes. For
   example, if you check for the subtypes lang-en and phonetic and if
   the attribute name is cn;lang-en;phonetic, this method returns true.
   If the attribute name is cn;phonetic or cn;lang-en, this method
   returns false.

   Parameters are:

      subtypes       An array of subtypes to check for.

5.1.13 removeValue

   public synchronized void removeValue(String attrString)

   Removes a string value from the attribute.

   public synchronized void removeValue(byte attrBytes[])

   Removes a byte[]-formatted value from the attribute.

   Parameters are:

Expires April 8, 2000                                        [Page 16]

JAVA LDAP API                                             October 1999

      attrString     Value of the attribute as a String.

      attrBytes      Value of the attribute as raw bytes.

5.1.14 size

   public int size()

   Returns the number of values of the attribute.

5.2 public class LDAPAttributeSchema
                 extends LDAPSchemaElement

   The LDAPAttributeSchema class represents the definition of an
   attribute. It is used to query attribute syntax, and to add or delete
   an attribute definition in a Directory. See [2] for a description of
   attribute representation in LDAP.

5.2.1 Constructors

   public LDAPAttributeSchema(String name,
                              String oid,
                              String description,
                              String syntaxString,
                              boolean single
                              String superior,
                              String[] aliases)

   Constructs an attribute definition for adding to or deleting from a
   Directory.

   public LDAPAttributeSchema(String raw)

   Constructs an attribute definition from the raw String value returned
   on a Directory query for "attributetypes".

   Parameters are:

      name           Name of the attribute.

      oid            Unique Object Identifer of the attribute - in
                      dotted numerical format.

      description    Optional description of the attribute.

      syntaxString   Unique Object Identifer of the syntax of the
                      attribute - in dotted numerical format.

Expires April 8, 2000                                        [Page 17]

JAVA LDAP API                                             October 1999

      single         True if the attribute is to be single-valued.

      superior       Optional name of the attribute type which this
                      attribute type derives from; null if there is no
                      superior attribute type.

      aliases        Optional list of additional names by which the
                      attribute may be known; null if there are no
                      aliases.

      raw            The raw String value returned on a Directory
                      query for "attributetypes".

5.2.2 getSyntaxString

   public String getSyntaxString()

   Returns the Unique Object Identifer of the syntax of the attribute in
   dotted numerical format.

5.2.3 getSuperior

   public String getSuperior()

   Returns the name of the attribute type which this attribute derives
   from, or null if there is no superior attribute.

5.2.4 isSingleValued

   public boolean isSingleValued()

   Returns true if the attribute is single-valued.

5.3 public class LDAPAttributeSet
                 implements Cloneable

   An LDAPAttributeSet is a collection of LDAPAttributes, as returned in
   an entry on a search or read operation, or used to construct an entry
   to be added to a directory.

5.3.1 Constructors

   public LDAPAttributeSet()

   Constructs a new set of attributes. This set is initially empty.

Expires April 8, 2000                                        [Page 18]

JAVA LDAP API                                             October 1999

5.3.2 add

   public synchronized void add(LDAPAttribute attr)

   Adds the specified attribute to this attribute set.

   Parameters are:

      attr           Attribute to add to this set.

5.3.3 clone

   public Object clone()

   Returns a deep copy of this attribute set.

5.3.4 elementAt

   public LDAPAttribute elementAt(int index)
                               throws ArrayIndexOutOfBoundsException

   Returns the attribute at the position specified by the index. The
   index is 0-based.

   Parameters are:

      index           Index of the attribute to get.

5.3.5 getAttribute

   public LDAPAttribute[] getAttribute(String attrName)
   Returns the attribute matching the specified attrName. For example,

        getAttribute("cn")          returns only the "cn" attribute
        getAttribute("cn;lang-en")  returns only the "cn;lang-en"
                                    attribute.

   In both cases, null is returned if there is no exact match to the
   specified attrName.

   public LDAPAttribute[] getAttribute(String attrName, String lang)

   Returns a single best-match attribute, or none if no match is
   available in the entry.

Expires April 8, 2000                                        [Page 19]

JAVA LDAP API                                             October 1999

   LDAP version 3 allows adding a subtype specification to an attribute
   name. "cn;lang-ja", for example, indicates a Japanese language
   subtype of the "cn" attribute. "cn;lang-ja-JP-kanji" may be a subtype
   of "cn;lang-ja". This feature may be used to provide multiple
   localizations in the same Directory. For attributes which do not vary
   among localizations, only the base attribute may be stored, whereas
   for others there may be varying degrees of specialization.

   getAttribute(attrName,lang) returns the subtype that matches attrName
   and that best matches lang. If there are subtypes other than "lang"
   subtypes included in attrName, e.g. "cn;binary", only attributes with
   all of those subtypes are returned. If lang is null or empty, the
   method behaves as getAttribute(attrName). If there are no matching
   attributes, null is returned.

   Example:

      Assume the entry contains only the following attributes:

         cn;lang-en
         cn;lang-ja-JP-kanji
         sn

         getAttribute( "cn" )               returns null.
         getAttribute( "sn" )               returns the "sn" attribute.
         getAttribute( "cn", "lang-en-us" ) returns the "cn;lang-en"
                                            attribute.
         getAttribute( "cn", "lang-en" )    returns the "cn;lang-en"
                                            attribute.
         getAttribute( "cn", "lang-ja" )    returns null.
         getAttribute( "sn", "lang-en" )    returns the "sn" attribute.

   Parameters are:

   attrName     The name of an attribute to retrieve, with or without
   subtype specification(s). "cn", "cn;phonetic", and cn;binary" are
   valid attribute names.

      lang           A language specification as in [10], with
                      optional subtypes appended using "-" as
                      separator. "lang-en", "lang-en-us", "lang-ja",
                      and "lang-ja-JP-kanji" are valid language
                      specification.

5.3.6 getAttributes

   public Enumeration getAttributes()

   Returns an enumeration of the attributes in this attribute set.

Expires April 8, 2000                                        [Page 20]

JAVA LDAP API                                             October 1999

5.3.7 getSubset

   public LDAPAttributeSet getSubset(String subtype)

   Creates a new attribute set containing only the attributes that have
   the specified subtypes.

   For example, suppose an attribute set contains the following
   attributes:

         cn
         cn;lang-ja
         sn;phonetic;lang-ja
         sn;lang-us

   Calling the getSubset method and passing lang-ja as the argument, the
   method returns an attribute set containing the following attributes:

         cn;lang-ja
         sn;phonetic;lang-ja

   Parameters are:

      subtype - Semi-colon delimited list of subtypes to include. For
                      example:
                     "lang-ja"        // Only Japanese language
                      subtypes
                     "binary"         // Only binary subtypes
                     "binary;lang-ja" // Only Japanese language
                      subtypes
                                         which also are binary

5.3.8 remove

   public synchronized void remove(String name)

   Removes the specified attribute from the set. If the attribute is not
   a member of the set, nothing happens.

   Parameters are:

      name           Name of the attribute to remove from this set. To
                      remove an LDAPAttribute by object, the
                      LDAPAttribute.getName method can be used:
                      LDAPAttributeSet.remove( attr.getName() );

5.3.9 removeElementAt

Expires April 8, 2000                                        [Page 21]

JAVA LDAP API                                             October 1999

   public void removeElementAt(int index)
                               throws ArrayIndexOutOfBoundsException

   Removes the attribute at the position specified by the index.  The
   index is 0-based.

   Parameters are:

      index          Index of the attribute to remove.

5.3.10 size

   public int size()

   Returns the number of attributes in this set.

5.4 public interface LDAPBind

   Used to do explicit bind processing on a referral. A client may
   specify an instance of this class to be used on a single operation
   (through the LDAPConstraints object) or for all operations (through
   LDAPConnection.setOption()).

5.4.1 bind

   public void bind (LDAPConnection conn)
                     throws LDAPException

   This method is called by LDAPConnection when authenticating. An
   implementation may access the host, port, credentials, and other
   information in the LDAPConnection to decide on an appropriate
   authentication mechanism, and/or may interact with a user or external
   module. An LDAPException is thrown on failure, as in
   LDAPConnection.bind().

   Parameters are:

      conn           An established connection to an LDAP server.

5.5 public class LDAPCompareAttrNames
                 implements LDAPEntryComparator

   An object of this class supports sorting search results by attribute
   name, in ascending or descending order.

5.5.1 Constructors

Expires April 8, 2000                                        [Page 22]

JAVA LDAP API                                             October 1999

   public LDAPCompareAttrNames(String attrName)

   Constructs an object that will sort results by a single attribute, in
   ascending order.

   public LDAPCompareAttrNames(String attrName,
                               boolean ascendingFlag)

   Constructs an object that will sort results by a single attribute, in
   either ascending or descending order.

   public LDAPCompareAttrNames(String[] attrNames)

   Constructs an object that will sort by one or more attributes, in the
   order provided, in ascending order.

   public LDAPCompareAttrNames(String[] attrNames,
                               boolean[] ascendingFlags)
                               throws LDAPException

   Constructs an object that will sort by one or more attributes, in the
   order provided, in either ascending or descending order for each
   attribute.

   Parameters are:

      attrName       Name of an attribute to sort by.

      attrNames      Array of names of attributes to sort by.

      ascendingFlag  true to sort in ascending order, false for
                      descending order.

      ascendingFlags Array of flags, one for each attrName, where each
                      one is true to sort in ascending order, false for
                      descending order. An LDAPException is thrown if
                      the length of ascendingFlags is not greater than
                      or equal to the length of attrNames.

5.5.2 getLocale

   public Locale getLocale ()

   Returns the Locale to be used for sorting, if a Locale has been
   specified. If null, a basic String.compareTo() is used for collation.
   If non-null, a Locale-specific collation is used.

Expires April 8, 2000                                        [Page 23]

JAVA LDAP API                                             October 1999

5.5.3 setLocale

   public void setLocale (Locale locale)

   Sets the Locale to be used for sorting.

   Parameters are:

      locale         The Locale to be used for sorting.

5.5.4 isGreater

   public boolean isGreater (LDAPEntry entry1, LDAPEntry entry2)

   Returns true if entry1 is to be considered greater than entry2, for
   the purpose of sorting, based on the attribute name or names provided
   on object construction.

   Parameters are:

      entry1         Target entry for comparison.

      entry2         Entry to be compared to.

5.6 public class LDAPConnection
                 implements LDAPv3, Cloneable

   LDAPConnection is the central class that encapsulates the connection
   to a Directory Server through the LDAP protocol. It implements the
   LDAPv2 and LDAPv3 interfaces. An LDAPConnection object is not
   connected on construction, and may only be connected to one server at
   one port. Multiple threads may share this single connection, and an
   application may have more than one LDAPConnection object, connected
   to the same or different Directory Servers.

   Besides the methods described for LDAPv2 and LDAPv3, LDAPConnection
   provides the following methods.

5.6.1 Constructors

   public LDAPConnection()

   Constructs a new LDAPConnection object, which represents a connection
   to an LDAP server.

   Calling the constructor does not actually establish the connection.
   To connect to the LDAP server, use the connect method.

Expires April 8, 2000                                        [Page 24]

JAVA LDAP API                                             October 1999

   public LDAPConnection(LDAPSocketFactory factory)

   Constructs a new LDAPConnection object, which will use the supplied
   class factory to construct a socket connection during
   LDAPConnection.connect().

   Parameters are:

      factory         An object capable of producing a Socket.

5.6.2 clone

   public Object clone()

   Returns a copy of the object with a private context, but sharing the
   network connection if there is one. The network connection remains
   open until all clones have disconnected or gone out of scope. Any
   connection opened after cloning is private to the object making the
   connection.

   The clone can freely modify options and search constraints, and issue
   requests, without affecting the source object or other clones. If the
   clone disconnects or reconnects, it is completely dissociated from
   the source object and other clones. Reauthenticating in a clone,
   however, is a global operation which will affect the source object
   and all associated clones, because it applies to the single shared
   physical connection. Any request by an associated object after one
   has reauthenticated will carry the new identity.

5.6.3 finalize

   public void finalize() throws LDAPException

   Closes the connection if open and releases any other resources held
   by the object.

5.6.4 getAuthenticationDN

   public String getAuthenticationDN()

   Returns the distinguished name (DN) used for authentication by this
   object. null is returned if no authentication has been performed.

5.6.5 getAuthenticationMethod

   public String getAuthenticationMethod()

Expires April 8, 2000                                        [Page 25]

JAVA LDAP API                                             October 1999

   Returns the method used to authenticate the connection. The return
   value is one of the following:

      "none"         If the connection is not authenticated

      "simple"       If simple authentication was used, also if a null
                      or empty authentication DN was specified

      "sasl"         If a SASL mechanism was used to authenticate

5.6.6 getAuthenticationPassword

   public String getAuthenticationPassword()

   Returns the password used for simple authentication by this object.
   null is returned if no authentication has been performed.

5.6.7 getHost

   public String getHost()

   Returns the host name of the LDAP server to which the object is or
   was last connected, in the format originally specified.

5.6.8 getInputStream

   public InputStream getInputStream()

   Returns the stream used by the connection object for receiving data
   from the LDAP server.

5.6.9 getOutputStream

   public OutputStream getOutputStream()

   Returns the stream used by the connection object to send data to the
   LDAP server.

5.6.10 getPort

   public int getPort()

   Returns the port number of the LDAP server to which the object is or
   was last connected.

Expires April 8, 2000                                        [Page 26]

JAVA LDAP API                                             October 1999

5.6.11 getProperty

   public Object getProperty(String name) throws LDAPException

   Gets a property of a connection object.

   Parameters are:

      name            Name of the property to be returned.

                      The following read-only properties are available
                      for any given connection:

                      LDAP_PROPERTY_SDK            The version of this
                                                    SDK, as a Float
                                                    data type.

                      LDAP_PROPERTY_PROTOCOL       The highest
                                                    supported version
                                                    of the LDAP
                                                    protocol, as a
                                                    Float data type.

                      LDAP_PROPERTY_SECURITY       A comma-separated
                                                    list of the types
                                                    of authentication
                                                    supported, as a
                                                    String.

      Other properties may be available in particular implementations
      of the class, and used to modify operations such as search.

      A deep copy of the property is provided where applicable; a
      client does not need to clone the object received.

      An LDAPException is thrown if the requested property is not
      available.

5.6.12 getConstraints

   public LDAPConstraints getConstraints()

   Returns the set of constraints that apply to all operations performed
   through this connection (unless a different set of constraints is
   specified when calling an operation method).

Expires April 8, 2000                                        [Page 27]

JAVA LDAP API                                             October 1999

   Note that the getOption method can be used to get individual
   constraints (rather than getting the entire set of constraints).

5.6.13 getSearchConstraints

   public LDAPSearchConstraints getSearchConstraints()

   Returns the set of constraints that apply to search operations
   performed through this connection (unless a different set of
   constraints is specified when calling the search operation method).

5.6.14 getSocketFactory

   public LDAPSocketFactory getSocketFactory()

   Returns the LDAPSocketFactory used to establish a connection to a
   server.

5.6.15 isBound

   public boolean isBound()

   Indicates whether the object has authenticated to the connected LDAP
   server.

5.6.16 isConnected

   public boolean isConnected()

   Indicates whether the connection represented by this object is open
   at this time.

5.6.17 read

   public static LDAPEntry read(LDAPUrl toGet) throws LDAPException

   public static LDAPEntry read(LDAPUrl toGet,
                                LDAPSearchConstraints cons)
                                throws LDAPException

   Reads the entry specified by the LDAP URL.

   When this method is called, a new connection is created
   automatically, using the host and port specified in the URL. After
   finding the entry, the method closes the connection (in other words,
   it disconnects from the LDAP server).

   If the URL specifies a filter and scope, these are not used. Of the
   information specified in the URL, this method only uses the LDAP host

Expires April 8, 2000                                        [Page 28]

JAVA LDAP API                                             October 1999

   name and port number, the base distinguished name (DN), and the list
   of attributes to return.

   The method returns the entry specified by the base DN.

   Parameters are:

      toGet           LDAP URL specifying the entry to read.

      cons           Constraints specific to the operation.

5.6.18 search

   public static LDAPSearchResults search(LDAPUrl toGet)
   throws LDAPException

   Performs the search specified by the LDAP URL, returning an
   enumerable LDAPSearchResults object.

   public static LDAPSearchResults search(LDAPUrl toGet,
                                          LDAPSearchConstraints cons)
                                          throws LDAPException

   Perfoms the search specified by the LDAP URL. This method also allows
   specifying constraints for the search (such as the maximum number of
   entries to find or the maximum time to wait for search results).

   When this method is called, a new connection is created
   automatically, using the host and port specified in the URL. After
   all search results have been received from the server, the method
   closes the connection (in other words, it disconnects from the LDAP
   server).

   As part of the search constraints, a choice can be made as to whether
   to have the results delivered all at once or in smaller batches. If
   the results are to be delivered in smaller batches, each iteration
   blocks only until the next batch of results is returned.

   Parameters are:

      toGet          LDAP URL specifying the entry to read.

      cons           Constraints specific to the search.

5.6.19 setConstraints

   public void setConstraints(LDAPConstraints cons)

Expires April 8, 2000                                        [Page 29]

JAVA LDAP API                                             October 1999

   Sets the constraints that apply to all operations performed through
   this connection (unless a different set of constraints is specified
   when calling an operation method).

   Note that the setOption method can be used to set individual
   constraints (rather than setting the entire set of constraints).

5.6.20 setInputStream

   public void setInputStream(InputStream stream)

   Sets the stream used by the connection object for receiving data from
   the LDAP server.

5.6.21 setOutputStream

   public void setOutputStream(OutputStream stream)

   Sets the stream used by the connection object to send data to the
   LDAP server.

5.6.22 setProperty

   public void setProperty(String name, Object value)
        throws LDAPException

   Sets a property of a connection object.

   No property names have been defined at this time, but the mechanism
   is in place in order to support revisional as well as dynamic
   extensions to operation modifiers.

   Parameters are:

      name           Name of the property to set.

      value          Value to assign to the property.
                      An LDAPException is thrown if the specified
                      property is not supported.

5.6.23 setSearchConstraints

   public void setSearchConstraints(LDAPSearchConstraints cons)

   Sets the constraints that apply to all search operations performed
   through this connection (unless a different set of constraints is
   specified when calling a search operation method).

Expires April 8, 2000                                        [Page 30]

JAVA LDAP API                                             October 1999

   Typically, the setSearchConstraints method is used to create a
   slightly different set of search constraints to apply to a particular
   search.

5.6.24 setSocketFactory

   public void setSocketFactory(LDAPSocketFactory factory)

   Establishes the default LDAPSocketFactory used to establish a
   connection to a server.

   This method is implemented as once-only. It is useful to be able to
   change the run-time connection behavior of a whole application with a
   single instruction, but the results would be confusing, and the side-
   effects dangerous, if the global default factory could be changed at
   arbitrary times by different threads. It should be called before the
   first connect(). If called (for the first time) after connecting, the
   new factory will not be used until/unless a new connection is
   attempted with the object.

   A typical usage would be:

       if (usingTLS) {
           LDAPConnection.setSocketFactory(myTLSFactory);
       }
       ...
       LDAPConnection conn = new LDAPConnection();
       conn.connect(myHost, myPort);

   In this example, connections are constructed with the default
   LDAPSocketFactory.  At application start-up time, the default may be
   set to use a particular provided TLS socket factory.

   Parameters are:

      factory        A factory object which can construct socket
                      connections for an LDAPConnection.

5.7 public class LDAPConstraints

   A set of options to control any operation. There is always an
   LDAPConstraints associated with an LDAPConnection object; its
   values can be changed with LDAPConnection.setOption, or overridden by
   passing an LDAPConstraints object to an operation.

5.7.1 Constructors

   public LDAPConstraints()

Expires April 8, 2000                                        [Page 31]

JAVA LDAP API                                             October 1999

   Constructs an LDAPConstraints object that specifies the default
   set of constraints.

   public LDAPConstraints(int msLimit,
                          boolean doReferrals,
                          LDAPBind binder,
                          int hop_limit)

   public LDAPConstraints(int msLimit,
                          boolean doReferrals,
                          LDAPRebind reauth,
                          int hop_limit)

   Constructs a new LDAPConstraints object and allows specifying
   the operational constraints in that object.

   Parameters are:

      msLimit         Maximum time in milliseconds to wait for results
                      (0 by default, which means that there is no
                      maximum time limit). This is an interface-imposed
                      limit.

      doReferrals     Specify true to follow referrals automatically,
                      or false to throw an LDAPReferralException error
                      if the server sends back a referral (false by
                      default).

      binder         Custom authentication processor, called when the
                      LDAPConnection needs to authenticate, typically
                      on following a referral. null may be specified to
                      indicate default authentication processing.

      reauth          Specifies an object of the class that implements
                      the LDAPRebind interface. The object will be used
                      when the client follows referrals automatically.
                      The object provides a method for getting the
                      distinguished name and password used to
                      authenticate to another LDAP server during a
                      referral. Specifying null indicates the default
                      LDAPRebind will be used if one has been assigned
                      with LDAPConnection.setOption(), or anonymous
                      authentication otherwise.

      hop_limit       Maximum number of referrals to follow in a
                      sequence when attempting to resolve a request,
                      when doing automatic referral following.

5.7.2 getHopLimit

Expires April 8, 2000                                        [Page 32]

JAVA LDAP API                                             October 1999

   public int getHopLimit()

   Returns the maximum number of hops to follow during automatic
   referral following.

5.7.3 getBindProc

   public LDAPBind getBindProc()

   Returns an object that can process authentication. It may be null.

5.7.4 getRebindProc

   public LDAPRebind getRebindProc()

   Returns the object that provides the method for getting
   authentication information. It may be null.

5.7.5 getReferrals

   public boolean getReferrals()

   Specifies whether nor not referrals are followed automatically.
   Returns true if referrals are to be followed automatically, or false
   if referrals throw an LDAPReferralException.

5.7.6 getTimeLimit

   public int getTimeLimit()

   Returns the maximum number of milliseconds to wait for any operation
   under these constraints. If 0, there is no maximum time limit
   on waiting for the operation results. The actual granularity of the
   timeout depends on the implementation.

5.7.7 setHopLimit

   public void setHopLimit(int hop_limit)

   Sets the maximum number of hops to follow in sequence during
   automatic referral following. The default is 5.

   Parameters are:

      hop_limit      Maximum number of chained referrals to follow
                      automatically.

Expires April 8, 2000                                        [Page 33]

JAVA LDAP API                                             October 1999

5.7.8 setBindProc

   public void setBindProc(LDAPBind binder)

   Specifies the object that will process authentication requests. The
   default is null.

   Parameters are:

      binder         An object that implements LDAPBind.

5.7.9 setRebindProc

   public void setRebindProc(LDAPRebind reauth)

   Specifies the object that provides the method for getting
   authentication information. The default is null. If referrals is set
   to true, and the reauth is null, referrals will be followed with
   anonymous (= no) authentication.

   Parameters are:

      reauth         An object that implements LDAPRebind.

5.7.10 setReferrals

   public void setReferrals(boolean doReferrals)

   Specifies whether nor not referrals are followed automatically, or if
   referrals throw an LDAPReferralException.  Referrals of any type
   other than to an LDAP server (i.e. a referral URL other than
   ldap://something) are ignored on automatic referral following. The
   default is false.

   Parameters are:

      doReferrals    True to follow referrals automatically.

5.7.11 setTimeLimit

   public void setTimeLimit(int msLimit)

   Sets the maximum number of milliseconds to wait for any operation
   under these search constraints. If 0, there is no maximum time limit
   on waiting for the operation results. The actual granularity of the
   timeout depends on the implementation.

   Parameters are:

Expires April 8, 2000                                        [Page 34]

JAVA LDAP API                                             October 1999

      msLimit        Maximum milliseconds to wait.

5.7.12 getClientControls

   public LDAPControl[] getClientControls()

   Returns controls to be used by the interface.

5.7.13 getServerControls

   public LDAPControl[] getServerControls()

   Returns controls to be sent to the server.

5.7.14 setClientControls

   public void setClientControls( LDAPControl control )

   public void setClientControls( LDAPControl[] controls )

   Sets controls for use by the interface.

   Parameters are:

      control        A single client control.

      controls       An array of client controls.

5.7.15 setServerControls

   public void setServerControls( LDAPControl control )

   public void setServerControls( LDAPControl[] controls )

   Sets controls to be sent to the server.

   Parameters are:

      control        A single control to be sent to the server.

      controls       An array of controls to be sent to the server.

5.8 public class LDAPControl
                 implements Cloneable

   An LDAPControl encapsulates optional additional parameters or
   constraints to be applied to LDAP operations. If set as a Server

Expires April 8, 2000                                        [Page 35]

JAVA LDAP API                                             October 1999

   Control, it is sent to the server along with operation requests. If
   set as a Client Control, it is not sent to the server, but rather
   interpreted locally by the client. LDAPControl is an LDAPv3
   extension, and is not supported in an LDAPv2 environment.

5.8.1 Constructors

   public LDAPControl(String id,
                      boolean critical,
                      byte vals[])

   Parameters are:

      id             The type of the Control, as a string.

      critical       True if the LDAP operation should be discarded if
                      the server does not support this Control.

      vals           Control-specific data.

5.8.2 clone

   public Object clone()

   Returns a deep copy of the object.

5.8.3 getID

   public String getID()

   Returns the identifier of the control.

5.8.4 getValue

   public byte[] getValue()

   Returns the control-specific data of the object.

5.8.5 isCritical

   public boolean isCritical()

   Returns true if the control must be supported for an associated
   operation to be executed.

Expires April 8, 2000                                        [Page 36]

JAVA LDAP API                                             October 1999

5.8.6 newInstance

   public static LDAPControl newInstance(byte[] data)

   Instantiates a control, given the raw data representing it in an LDAP
   message.

5.8.7 register

   public static void register(String oid, Class controlClass)

   Registers a class to be instantiated on receipt of a control with the
   given oid. Any previous registration for the oid is overridden. The
   controlClass must be an extension of LDAPControl.

   Parameters are:

      oid            The Object Identifier of the Control.

      controlClass   A class which can instantiate an LDAPControl.

5.9 public class LDAPDN

   A utility class representing a distinguished name (DN).

5.9.1 equals

   public static boolean equals (String dn1, String dn2)

   Returns true if the two strings correspond to the same DN, after
   appropriate normalization.

   Parameters are:

      dn1            String form of first DN to compare.

      dn2            String form of second DN to compare.

5.9.2 escapeRDN

   public static String escapeRDN (String rdn)

   Returns the RDN after escaping the characters requiring escaping [6].
   For example, for the rdn “cn=Acme, Inc”, “cn=Acme\, Inc” is returned.

   Parameters are:

      rdn            The RDN to escape.

Expires April 8, 2000                                        [Page 37]

JAVA LDAP API                                             October 1999

5.9.3 unescapeRDN

   public static String unescapeRDN (String rdn)

   Returns the RDN after unescaping the characters requiring escaping
   [6]. For example, for the rdn “cn=Acme\, Inc”, “cn=Acme, Inc” is
   returned.

   Parameters are:

      rdn            The RDN to unescape.

5.9.4 explodeDN

   public static String[] explodeDN(String dn,
                                    boolean noTypes)

   Returns the individual components of a distinguished name (DN).

   Parameters are:

      dn             Distinguished name, e.g. "cn=Babs
                      Jensen,ou=Accounting,o=Acme,c=us"

      noTypes        If true, returns only the values of the
                      components, and not the names, e.g. "Babs
                      Jensen", "Accounting", "Acme", "us" - instead of
                      "cn=Babs Jensen", "ou=Accounting", "o=Acme", and
                      "c=us".

5.9.5 explodeRDN

   public static String[] explodeRDN(String rdn,
                                     boolean noTypes)

   Returns the individual components of a relative distinguished name
   (RDN).

   Parameters are:

      rdn            Relative distinguished name, i.e. the left-most
                      component of a distinguished name.

      noTypes        If true, returns only the values of the
                      components, and not the names.

Expires April 8, 2000                                        [Page 38]

JAVA LDAP API                                             October 1999

5.10 public class LDAPEntry

   An LDAPEntry represents a single entry in a directory, consisting of
   a distinguished name (DN) and zero or more attributes. An instance of
   LDAPEntry is created in order to add an entry to a Directory, and
   instances are returned on a search by enumerating an
   LDAPSearchResults.

5.10.1 Constructors

   public LDAPEntry()

   Constructs an empty entry.

   public LDAPEntry(String dn)

   Constructs a new entry with the specified distinguished name and with
   an empty attribute set.

   public LDAPEntry(String dn,
                    LDAPAttributeSet attrs)

   Constructs a new entry with the specified distinguished name and set
   of attributes.

   Parameters are:

      dn             The distinguished name of the new entry. The
                      value is not validated. An invalid distinguished
                      name will cause adding of the entry to a
                      directory to fail.

      attrs          The initial set of attributes assigned to the
                      entry.

5.10.2 getAttribute

   public LDAPAttribute[] getAttribute(String attrName)

   Returns the attributes matching the specified attrName.

   Parameters are:

      attrName       The name of the attribute or attributes to
                      return. See 5.3.5 for the syntax and semantics
                      relevant to this parameter.

Expires April 8, 2000                                        [Page 39]

JAVA LDAP API                                             October 1999

5.10.3 getAttributeSet

   public LDAPAttributeSet getAttributeSet()

   Returns the attribute set of the entry. All base and subtype variants
   of all attributes are returned. The LDAPAttributeSet returned may be
   empty if there are no attributes in the entry.

   public LDAPAttributeSet getAttributeSet(String subtype)

   Returns an attribute set from the entry, consisting of only those
   attributes matching the specified subtype(s). This may be used to
   extract only a particular language variant subtype of each attribute,
   if it exists. "subtype" may be, for example, "lang-ja", "binary", or
   "lang-ja;phonetic". If more than one subtype is specified, separated
   with a semicolon, only those attributes with all of the named
   subtypes will be returned.  The LDAPAttributeSet returned may be
   empty if there are no matching attributes in the entry.

   Parameters are:

      subtype        One or more subtype specification(s), separated
                      with semicolons.  "lang-ja" and
                      "lang-en;phonetic" are valid subtype
                      specifications.

5.10.4 getDN

   public String getDN()

   Returns the distinguished name of the entry.

5.11 public class LDAPExtendedOperation

   An LDAPExtendedOperation encapsulates an ID which uniquely identifies
   a particular extended operation, known to a particular server, and
   the data associated with the operation.

5.11.1 Constructors

   public LDAPExtendedOperation(String oid,
                                byte[] vals)

   Constructs a new object with the specified object ID and data.

   Parameters are:

      oid            The unique identifier of the operation.

Expires April 8, 2000                                        [Page 40]

JAVA LDAP API                                             October 1999

      vals           The operation-specific data of the operation.

5.11.2 getID

   public String getID()

   Returns the unique identifier of the operation.

5.11.3 getValue

   public byte[] getValue()

   Returns the operation-specific data (not a copy, a reference).

5.12 public interface LDAPEntryComparator

   An object of this class can implement arbitrary sorting algorithms
   for search results.

5.12.1 isGreater

   public boolean isGreater(LDAPEntry entry1, LDAPEntry entry2)

   Returns true if entry1 is to be considered greater than or equal to
   entry2, for the purpose of sorting.

   Parameters are:

      entry1         Target entry for comparison.

      entry2         Entry to be compared to.

5.13 public class LDAPException
                  extends Exception

   Thrown to indicate that an error has occurred. An LDAPException can
   result from physical problems (such as network errors) as well as
   problems with LDAP operations (for example, if the LDAP add operation
   fails because of a duplicate entry).

   Most errors that occur throw this type of exception.  The
   getLDAPResultCode() method returns the specific result code, which
   can be compared against standard LDAP result codes as defined in [6],
   section 4.

Expires April 8, 2000                                        [Page 41]

JAVA LDAP API                                             October 1999

5.13.1 Constructors

   public LDAPException()

   Constructs a default exception with no specific error information.

   public LDAPException(String message,
                        int resultCode)

   Constructs an exception with an error code and a specified string as
   additional information.

   Parameters are:

      message        The additional error information.

      resultCode     The result code returned

5.13.2 errorCodeToString

   public String errorCodeToString()

   Returns a String representing the internal error code, in the default
   Locale.

   public static String errorCodeToString( int code )

   Returns a String representing an arbitrary error code, in the default
   Locale, or null if there is no such code.

   public String errorCodeToString( Locale locale )

   Returns a String representing the internal error code, in the
   specified Locale, or null if a String representation is not available
   for the requested Locale.

   public static String errorCodeToString( int code, Locale locale )

   Returns a String representing an arbitrary error code, in the
   specified Locale, or null if there is no such code or if a String
   representation is not available for the requested Locale.

   Parameters are:

Expires April 8, 2000                                        [Page 42]

JAVA LDAP API                                             October 1999

      code           One of the error codes listed in "Error codes"
                      below.

      locale         A Locale in which to render the error String.

5.13.3 getLDAPErrorMessage

   public String getLDAPErrorMessage()

   Returns the error message, if this message is available (that is, if
   this message was set). If the message was not set, this method
   returns null.

5.13.4 getLDAPResultCode

   public int getLDAPResultCode()

   Returns the result code from the exception. The codes are defined as
   public final static int members of this class. If the exception is a
   result of error information returned from a directory operation, the
   code will be one of those defined in [6]. Otherwise, a local error
   code is returned (see "Error codes" below).

5.13.5 getMatchedDN

   public String getMatchedDN()

   Returns the part of a submitted distinguished name which could be
   matched by the server. If the exception was caused by a local error,
   such as no server available, the return value is null. If the
   exception resulted from an operation being executed on a server, the
   value is an empty String except when the result of the operation was
   one of the following:

      NO_SUCH_OBJECT
      ALIAS_PROBLEM
      INVALID_DN_SYNTAX
      ALIAS_DEREFERENCING_PROBLEM

5.13.6 Error codes

   See [6] for a discussion of the meanings of the codes.

        ADMIN_LIMIT_EXCEEDED
        AFFECTS_MULTIPLE_DSAS
        ALIAS_DEREFERENCING_PROBLEM
        ALIAS_PROBLEM
        ATTRIBUTE_OR_VALUE_EXISTS

Expires April 8, 2000                                        [Page 43]

JAVA LDAP API                                             October 1999

        AUTH_METHOD_NOT_SUPPORTED
        BUSY
        COMPARE_FALSE
        COMPARE_TRUE
        CONFIDENTIALITY_REQUIRED
        CONSTRAINT_VIOLATION
        ENTRY_ALREADY_EXISTS
        INAPPROPRIATE_AUTHENTICATION
        INAPPROPRIATE_MATCHING
        INSUFFICIENT_ACCESS_RIGHTS
        INVALID_ATTRIBUTE_SYNTAX
        INVALID_CREDENTIALS
        INVALID_DN_SYNTAX
        IS_LEAF
        LDAP_PARTIAL_RESULTS
        LOOP_DETECT
        NAMING_VIOLATION
        NO_SUCH_ATTRIBUTE
        NO_SUCH_OBJECT
        NOT_ALLOWED_ON_NONLEAF
        NOT_ALLOWED_ON_RDN
        OBJECT_CLASS_MODS_PROHIBITED
        OBJECT_CLASS_VIOLATION
        OPERATIONS_ERROR
        OTHER
        PROTOCOL_ERROR
        REFERRAL
        SASL_BIND_IN_PROGRESS
        SIZE_LIMIT_EXCEEDED
        STRONG_AUTH_REQUIRED
        SUCCESS
        TIME_LIMIT_EXCEEDED
        UNAVAILABLE
        UNAVAILABLE_CRITICAL_EXTENSION
        UNDEFINED_ATTRIBUTE_TYPE
        UNWILLING_TO_PERFORM

   Local errors, resulting from actions other than an operation on a
   server, are among the following, listed in [8]:

        AUTH_UNKNOWN
        CLIENT_LOOP
        CONNECT_ERROR
        CONTROL_NOT_FOUND
        DECODING_ERROR
        ENCODING_ERROR
        FILTER_ERROR
        LOCAL_ERROR
        LDAP_NOT_SUPPORTED
        LDAP_TIMEOUT
        MORE_RESULTS_TO_RETURN
        NO_MEMORY

Expires April 8, 2000                                        [Page 44]

JAVA LDAP API                                             October 1999

        NO_RESULTS_RETURNED
        PARAM_ERROR
        REFERRAL_LIMIT_EXCEEDED
        SERVER_DOWN
        USER_CANCELLED

5.14 public class LDAPMatchingRuleSchema
                  extends LDAPSchemaElement

   The LDAPMatchingRuleSchema class represents the definition of a
   matching rule. It is used to query matching rule syntax, and to add
   or delete a matching rule definition in a Directory. See [2] for a
   description of matching rule representation in LDAP.

5.14.1 Constructors

   public LDAPMatchingRuleSchema(String name,
                                 String oid,
                                 String description,
                                 String[] attributes,
                                 String syntaxString,
                                 String[] aliases)

   Constructs a matching rule definition for adding to or deleting from
   a Directory.

   public LDAPMatchingRuleSchema(String rawMatchingRule,
                                 String rawMatchingRuleUse)

   Constructs a matching rule definition from the raw String values
   returned on a Directory query for "matchingRule" and for
   "matchingRuleUse" for the same rule.

   Parameters are:

      name               Name of the attribute.

      oid                Unique Object Identifer of the attribute - in
                         dotted numerical format.

      description        Optional description of the attribute.

      attributes         OIDs of attributes to which the rule applies.

      syntaxString       Unique Object Identifer of the syntax of the
                         attribute - in dotted numerical format.

Expires April 8, 2000                                        [Page 45]

JAVA LDAP API                                             October 1999

      aliases            Optional list of additional names by which the
                         matching rule may be known; null if there are
                         no aliases.

      rawMatchingRule    The raw String value returned on a Directory
                         query for "matchingRule".

      rawMatchingRuleUse The raw String value returned on a Directory
                         query for "matchingRuleUse".

5.14.2 getAttributes

   public String[] getAttributes()

   Returns the OIDs of the attributes to which this rule applies.

5.15 public class LDAPModification

   A single change specification for an LDAPAttribute.

5.15.1 Constructors

   public LDAPModification(int op,
                           LDAPAttribute attr)

   Specifies a modification to be made to an attribute.

   Parameters are:

      op             The type of modification to make, which can be
                      one of the following:

               LDAPModification.ADD     The value should be added to
                                        the attribute

               LDAPModification.DELETE  The value should be removed
                                        from the attribute

               LDAPModification.REPLACE The value should replace all
                                        existing values of the
                                        attribute

      attr           The attribute (possibly with values) to be
                      modified.

Expires April 8, 2000                                        [Page 46]

JAVA LDAP API                                             October 1999

5.15.2 getAttribute

   public LDAPAttribute getAttribute()

   Returns the attribute (possibly with values) to be modified.

5.15.3 getOp

   public int getOp()

   Returns the type of modification specified by this object.

5.16 public class LDAPModificationSet

   A collection of modifications to be made to the attributes of a
   single entry.

5.16.1 Constructors

   public LDAPModificationSet()

   Constructs a new, empty set of modifications.

5.16.2 add

   public synchronized void add(int op,
                                LDAPAttribute attr)

   Specifies another modification to be added to the set of
   modifications.

   Parameters are:

      op             The type of modification to make, as described
                      for LDAPModification.

      attr           The attribute (possibly with values) to be
                      modified.

5.16.3 elementAt

   public LDAPModification elementAt(int index)
                               throws ArrayIndexOutOfBoundsException

   Retrieves a particular LDAPModification object at the position
   specified by the index.

Expires April 8, 2000                                        [Page 47]

JAVA LDAP API                                             October 1999

   Parameters are:

      index          Index of the modification to get.

5.16.4 remove

   public synchronized void remove(String name)

   Removes the first attribute with the specified name in the set of
   modifications.

   Parameters are:

      name           Name of the attribute to be removed.

5.16.5 removeElementAt

   public void removeElementAt(int index)
                               throws ArrayIndexOutOfBoundsException

   Removes a particular LDAPModification object at the position
   specified by the index.

   Parameters are:

      index          Index of the modification to remove.

5.16.6 size

   public int size()

   Retrieves the number of LDAPModification objects in this set.

5.17 public class LDAPObjectClassSchema

   The LDAPObjectClassSchema class represents the definition of an
   object class. It is used to query the syntax of an object class, and
   to add or delete an object class definition in a Directory. See [2]
   for a description of object class representation in LDAP.

5.17.1 Constructors

   public LDAPObjectClassSchema(String name,
                                String oid,
                                String[] superiors,
                                String description,
                                String[] required,

Expires April 8, 2000                                        [Page 48]

JAVA LDAP API                                             October 1999

                                String[] optional,
                                int type,
                                String[] aliases)

   Constructs an object class definition for adding to or deleting from
   a Directory.

   public LDAPObjectClassSchema(String raw)

   Constructs an object class definition from the raw String value
   returned on a Directory query for "objectclasses".

   Parameters are:

      name           Name of the object class.

      oid            Unique Object Identifer of the object class - in
                      dotted numerical format.

      description    Optional description of the object class.

      superiors      The object classes this one derives from.

      required       A list of attributes required for an entry with
                      this object class.

      optional       A list of attributes acceptable but not required
                      for an entry with this object class.

      type           One of ABSTRACT, AUXILIARY, or STRUCTURAL. These
                      are constants defined in LDAPObjectClassSchema.

      aliases        Optional list of additional names by which the
                     object class may be known; null if there are no
                     aliases.

      raw            The raw String value returned on a Directory
                      query for "objectclasses".

5.17.2 getSuperiors

   public String[] getSuperiors()

   Returns the object classes which this one derives from.

5.17.3 getRequiredAttributes

   public String[] getRequiredAttributes()

Expires April 8, 2000                                        [Page 49]

JAVA LDAP API                                             October 1999

   Returns a list of attributes required of an entry with this object
   class.

5.17.4 getOptionalAttributes

   public String[] getOptionalAttributes()

   Returns a list of attributes acceptable but not required of an entry
   with this object class.

5.17.5 getType

   public int getType()

   Returns one of ABSTRACT, AUXILIARY, or STRUCTURAL. These are
   constants defined in LDAPObjectClassSchema.

5.18 public class LDAPRebindAuth

   Represents information used to authenticate the client in cases where
   the client follows referrals automatically.

5.18.1 Constructors

   public LDAPRebindAuth ( String dn,
                           String password )

   Constructs information that is used by the client for authentication
   when following referrals automatically.

   Parameters are:

      dn             Distinguished name to use in authenticating to
                      the server.

      password       Password to use in authenticating to the server.

5.18.2 getDN

   public String getDN()

   Returns the distinguished name to be used for reauthentication on
   automatic referral following.

5.18.3 getPassword

   public String getPassword()

Expires April 8, 2000                                        [Page 50]

JAVA LDAP API                                             October 1999

   Returns the password to be used for reauthentication on automatic
   referral following.

5.19 public interface LDAPRebind

   Used to provide credentials for reauthentication on processing a
   referral.

5.19.1 getRebindAuthentication

   public LDAPRebindAuth getRebindAuthentication (String host, int port)

   Returns an object which can provide credentials for authenticating to
   a server at the provided host name and port number.

   Parameters are:

      host           Contains a hostname or dotted string representing
                      the IP address of a host running an LDAP server.

      port           Contains the TCP or UDP port number to connect
                      to.

5.20 public class LDAPReferralException
                  extends LDAPException

   This exception, derived from LDAPException, is thrown when a server
   returns a referral and automatic referral following has not been
   enabled.

5.20.1 Constructors

   public LDAPReferralException()

   Constructs a default exception with no specific error information.

   public LDAPReferralException(String message)

   Constructs a default exception with a specified string as additional
   information. This form is used for lower-level errors.

   public LDAPReferralException(String message,
                                int resultCode,
                                String serverMessage)

Expires April 8, 2000                                        [Page 51]

JAVA LDAP API                                             October 1999

   Parameters are:

      message        The additional error information.

      resultCode     The result code returned

      serverMessage  Error message specifying additional information
                      from the server.

5.20.2 getURLs

   public LDAPUrl[] getURLs()

   Gets the list of referrals (LDAP URLs to other servers) returned by
   the LDAP server. This exception is only thrown, and therefor the URL
   list only available, if automatic referral following is not enabled.
   The referrals may include URLs of a type other than ones for an LDAP
   server (i.e. a referral URL other than ldap://something).

5.21 public class LDAPSchema

   The LDAPSchema supports querying a Directory Server for its schema,
   and obtaining definitions of individual schema elements.

5.21.1 Constructors

   public LDAPSchema()

   Constructs an empty LDAPSchema object.

5.21.2 fetchSchema

   public void fetchSchema(LDAPConnection ld) throws LDAPException

   Retrieves the entire schema from a Directory Server.

   public void fetchSchema(LDAPConnection ld,
                           String dn) throws LDAPException

   Retrieves the schema in effect at a particular entry in the Directory
   Server.

   The fetchSchema methods are the only methods that interact with a
   Directory Server. The other methods access information acquired
   through fetchSchema. An LDAPException is thrown as for
   LDAPConnection.search() (5.28.11) if the schema cannot be retrieved
   with the specified connection.

Expires April 8, 2000                                        [Page 52]

JAVA LDAP API                                             October 1999

   Parameters are:

      ld             An open connection to a Directory Server.

      dn             Distinguished name of the entry from which to
                      return schema. The subschemasubentry attribute of
                      the entry is queried to find the location of the
                      schema to be returned.

5.21.3 getAttribute

   public LDAPAttributeSchema getAttribute( String name )

   Returns a particular attribute definition, or null if not found.

   Parameters are:

      name           Name of the attribute for which a definition is
                      to be returned.

5.21.4 getObjectClass

   public LDAPObjectClassSchema getObjectClass( String name )

   Returns a particular object class definition, or null if not found.

   Parameters are:

      name           Name of the object class for which a definition
                      is to be returned.

5.21.5 getMatchingRule

   public LDAPMatchingRuleSchema getMatchingRule( String name )

   Returns a particular matching rule definition, or null if not found.

   Parameters are:

      name           Name of the matching rule for which a definition
                      is to be returned.

5.21.6 getAttributes

   public Enumeration getAttributes()

   Returns an enumeration of attribute definitions.

Expires April 8, 2000                                        [Page 53]

JAVA LDAP API                                             October 1999

5.21.7 getObjectClasses

   public Enumeration getObjectClasses()

   Returns an enumeration of object class definitions.

5.21.8 getMatchingRules

   public Enumeration getMatchingRules()

   Returns an enumeration of matching rule definitions.

5.21.9 getAttributeNames

   public Enumeration getAttributeNames()

   Returns an enumeration of attribute names.

5.21.10 getObjectClassNames

   public Enumeration getObjectClassNames()

   Returns an enumeration of object class names.

5.21.11 getMatchingRuleNames

   public Enumeration getMatchingRuleNames()

   Returns an enumeration of matching rule names.

5.22 public abstract class LDAPSchemaElement

   The LDAPSchemaElement class is the base class for representing schema
   elements in LDAP.

5.22.1 getAliases

   public String[] getAliases()

   Returns an array of alternative names of the element, or null if
   there are none. With respect to the protocol-level schema element
   syntax definition of [2], the array consists of all values but the
   first of the NAME qualifier.

Expires April 8, 2000                                        [Page 54]

JAVA LDAP API                                             October 1999

5.22.2 getDescription

   public String getDescription()

   Returns the description of the element. With respect to the protocol-
   level schema element syntax definition of [2], the value is that of
   the DESC qualifier.

5.22.3 getName

   public String getName()

   Returns the name of the element. With respect to the protocol-level
   schema element syntax definition of [2], the value is that of the
   first NAME qualifier.

5.22.4 getID

   public String getID()

   Returns the Unique Object Identifier of the element.

5.22.5 getQualifier

   public String[] getQualifier(String name)

   Returns an array of all values of a specified optional or non-
   standard qualifier of the element. This method may be used to access
   the values of vendor-specific qualifiers (which begin with "X-" [2]).

   Parameters are:

      name           The name of the qualifier, case-sensitive.

5.22.6 getQualifierNames

   public Enumeration getQualifierNames()

   Returns an enumeration of all qualifiers of the element which are not
   defined in [2].

5.22.7 isObsolete

   public boolean isObsolete()

   Returns true if the element is obsolete (has the OBSOLETE qualifier
   in its LDAP definition [2].

Expires April 8, 2000                                        [Page 55]

JAVA LDAP API                                             October 1999

5.22.8 getValue

   public String getValue()

   Returns a String in a format suitable for directly adding to a
   Directory, as a value of the particular schema element attribute.

5.22.9 setQualifier

   public void setQualifier(String name, String[] values)

   Sets the values of a specified optional or non-standard qualifier of
   the element. This method may be used to set the values of vendor-
   specific qualifiers (which begin with "X-" [2]).

   Parameters are:

      name           The name of the qualifier, case-sensitive.

      values         The values to set for the qualifier.

5.22.10 add

   public void add(LDAPConnection ld) throws LDAPException

   public void add(LDAPConnection ld, String dn) throws LDAPException

   Adds the definition to a Directory. An exception is thrown if the
   definition can't be added.

   Parameters are:

      ld             An open connection to a Directory Server.
                      Typically the connection must have been
                      authenticated to add a schema definition.

      dn             Entry at which to determine the SubschemaSubentry
                      to which the schema element is to be added.

5.22.11 remove

   public void remove(LDAPConnection ld) throws LDAPException

   public void remove(LDAPConnection ld, String dn) throws LDAPException

   Removes the definition from a Directory. An exception is thrown if
   the definition can't be removed.

Expires April 8, 2000                                        [Page 56]

JAVA LDAP API                                             October 1999

   Parameters are:

      ld             An open connection to a Directory Server.
                      Typically the connection must have been
                      authenticated to remove a schema definition.

      dn             Entry at which to determine the SubschemaSubentry
                      to remove the schema element from.

5.22.12 modify

   public void modify(LDAPConnection ld
                      LDAPSchemaElement newValue) throws LDAPException

   public void modify(LDAPConnection ld
                      LDAPSchemaElement newValue,
                      String dn) throws LDAPException

   Replace a single value of the schema element definition in the
   schema. An exception is thrown if the definition can't be modified.

   Parameters are:

      ld             An open connection to a Directory Server.
                      Typically the connection must have been
                      authenticated to modify a schema definition.

      newValue       The new schema element value.

      dn             Entry at which to determine the SubschemaSubentry
                      to store the schema change in.

5.23 public class LDAPSearchConstraints extends LDAPConstraints

   A set of options to control a search operation. There is always an

   LDAPSearchConstraints associated with an LDAPConnection object; its
   values can be changed with LDAPConnection.setOption, or overridden by
   passing an LDAPConstraints object to the search operation.

5.23.1 Constructors

   public LDAPSearchConstraints()

   Constructs an LDAPSearchConstraints object that specifies the default
   set of search constraints.

Expires April 8, 2000                                        [Page 57]

JAVA LDAP API                                             October 1999

   public LDAPSearchConstraints(int msLimit,
                                int serverTimeLimit,
                                int dereference,
                                int maxResults,
                                boolean doReferrals,
                                int batchSize,
                                LDAPBind binder,
                                int hop_limit)

   public LDAPSearchConstraints(int msLimit,
                                int serverTimeLimit,
                                int dereference,
                                int maxResults,
                                boolean doReferrals,
                                int batchSize,
                                LDAPRebind reauth,
                                int hop_limit)

   Constructs a new LDAPSearchConstraints object and allows specifying
   the operational constraints in that object.

   Parameters are:

      msLimit         Maximum time in milliseconds to wait for results
                      (0 by default, which means that there is no
                      maximum time limit). This is an interface-imposed
                      limit.

      serverTimeLimit Maximum time in seconds that the server should
                      spend returning results. This is a server-imposed
                      limit.

      dereference     Specifies when aliases should be dereferenced.
                      Must be either LDAP_DEREF_NEVER,
                      LDAP_DEREF_FINDING, LDAP_DEREF_SEARCHING, or
                      LDAP_DEREF_ALWAYS from LDAPv2
                      (LDAPv2.LDAP_DEREF_NEVER by default).

      maxResults      Maximum number of search results to return (1000
                      by default).

      doReferrals     Specify true to follow referrals automatically,
                      or false to throw an LDAPReferralException error
                      if the server sends back a referral (false by
                      default).

      batchSize       Specify the number of results to block on during
                      enumeration. 0 means to block until all results
                      are in (1 by default).

      binder         Custom authentication processor, called when the
                      LDAPConnection needs to authenticate, typically

Expires April 8, 2000                                        [Page 58]

JAVA LDAP API                                             October 1999

                      on following a referral. null may be specified to
                      indicate default authentication processing.

      reauth          Specifies an object of the class that implements
                      the LDAPRebind interface. The object will be used
                      when the client follows referrals automatically.
                      The object provides a method for getting the
                      distinguished name and password used to
                      authenticate to another LDAP server during a
                      referral. Specifying null indicates the default
                      LDAPRebind will be used if one has been assigned
                      with LDAPConnection.setOption(), or anonymous
                      authentication otherwise.

      hop_limit       Maximum number of referrals to follow in a
                      sequence when attempting to resolve a request,
                      when doing automatic referral following.

5.23.2 getBatchSize

   public int getBatchSize()

   Returns the number of results to block on during enumeration of
   search results. This should be 0 if intermediate results are not
   needed, and 1 if results are to be processed as they come in.

5.23.3 getDereference

   public int getDereference()

   Specifies when aliases should be dereferenced. Returns either
   LDAP_DEREF_NEVER, LDAP_DEREF_FINDING, LDAP_DEREF_SEARCHING, or
   LDAP_DEREF_ALWAYS from LDAPv2.

5.23.4 getMaxResults

   public int getMaxResults()

   Returns the maximum number of search results to be returned; 0 means
   no limit.

5.23.5 getServerTimeLimit

   public int getServerTimeLimit()

   Reports the maximum number of seconds that the server is to wait when
   returning search results while using this constraint object

Expires April 8, 2000                                        [Page 59]

JAVA LDAP API                                             October 1999

5.23.6 setBatchSize

   public void setBatchSize(int batchSize)

   Sets the suggested number of results to block on during enumeration
   of search results. This should be 0 if intermediate results are not
   needed, and 1 if results are to be processed as they come in.  The
   default is 1.

   Parameters are:

      batchSize      Blocking size on search enumerations.

5.23.7 setDereference

   public void setDereference(int dereference)

   Sets a preference indicating whether or not aliases should be
   dereferenced, and if so, when.

   Parameters are:

      dereference    Either LDAP_DEREF_NEVER, LDAP_DEREF_FINDING,
                      LDAP_DEREF_SEARCHING, or LDAP_DEREF_ALWAYS from
                      LDAPv2.

5.23.8 setMaxResults

   public void setMaxResults(int maxResults)

   Sets the maximum number of search results to be returned; 0 means no
   limit.  The default is 1000.

   Parameters are:

      maxResults     Maxumum number of search results to return.

5.23.9 setServerTimeLimit

   public void setServerTimeLimit(int seconds)

   Sets the maximum number of seconds that the server is to wait when
   returning search results. The parameter is only recognized on search
   operations.

5.24 public class LDAPSearchResults

Expires April 8, 2000                                        [Page 60]

JAVA LDAP API                                             October 1999

   An LDAPSearchResults object is returned from a search operation. It
   implements Enumeration, thereby providing access to all entries
   retrieved during the operation.

5.24.1 getCount

   public int getCount()

   Returns a count of the entries in the search result. If the search is
   asynchronous (batch size not 0), this reports the number of results
   received so far.

5.24.2 getResponseControls

   public LDAPControl[] getResponseControls()

   Returns the latest Server Controls returned by a Directory Server
   in the context of this search request, or null
   if no Server Controls were returned.

5.24.3 hasMoreElements

   public boolean hasMoreElements()

   Specifies whether or not there are more search results in the
   enumeration. If true, there are more search results.

5.24.4 next

   public LDAPEntry next() throws LDAPException

   Returns the next result in the enumeration as an LDAPEntry. If
   automatic referral following is disabled, and there are one or more
   referrals among the search results, next() will throw an
   LDAPReferralException the last time it is called, after all other
   results have been returned.

5.24.5 nextElement

   public Object nextElement()

   Returns the next result in the enumeration as an Object. This the
   default implementation of Enumeration.nextElement(). The returned
   value may be an LDAPEntry or an LDAPReferralException.

Expires April 8, 2000                                        [Page 61]

JAVA LDAP API                                             October 1999

5.24.6 sort

   public void sort(LDAPEntryComparator comp)

   Sorts all entries in the results using the provided comparison
   object. If the object has been partially or completely enumerated,
   only remaining elements are sorted. Sorting the results requires that
   they all be present. This implies that
   LDAPSearchResults.nextElement() will always block until all results
   have been retrieved, after a sort operation.

   The LDAPCompareAttrNames class is provided to support the common need
   to collate by a single or multiple attribute values, in ascending or
   descending order.  Examples are:

       res.sort(new LDAPCompareAttrNames("cn"));

       res.sort(new LDAPCompareAttrNames("cn", false));

       String[] attrNames = { "sn", "givenname" };
       res.sort(new LDAPCompareAttrNames(attrNames));

   Parameters are:

      comp            An object that implements the LDAPEntryComparator
                      interface to compare two objects of type
                      LDAPEntry.

5.25 public interface LDAPSocketFactory

   Used to construct a socket connection for use in an LDAPConnection.
   An implementation of this interface may, for example, provide a
   TLSSocket connected to a secure server.

5.25.1 makeSocket

   public Socket makeSocket(String host, int port)
                            throws IOException, UnknownHostException

   Returns a socket connected using the provided host name and port
   number.

   There may be additional makeSocket methods defined when interfaces to
   establish TLS and SASL authentication in the java environment have
   been standardized.

   Parameters are:

Expires April 8, 2000                                        [Page 62]

JAVA LDAP API                                             October 1999

      host           Contains a hostname or dotted string representing
                      the IP address of a host running an LDAP server
                      to connect to.

      port           Contains the TCP or UDP port number to connect to
                      or contact. The default LDAP port is 389.

5.26 public class LDAPSortKey

   Encapsulates parameters for sorting search results.

5.26.1 Constructors

   public LDAPSortKey( String keyDescription )

   Constructs a new LDAPSortKey object using a, possibly complex,
   sorting specification.

   public LDAPSortKey( String key, boolean reverse)

   Constructs a new LDAPSortKey object using an attribute name and a
   sort order.

   public LDAPSortKey( String key, boolean reverse, String matchRule)

   Constructs a new LDAPSortKey object using an attribute name, a sort
   order, and a matching rule.

   Parameters are:

      keyDescription A single attribute specification to sort by. If
                      prefixed with "-", reverse order sorting is
                      requested. A matching rule OID may be appended
                      following ":".

                      Examples:
                         "cn"
                         "-cn"
                         "-cn:1.2.3.4.5"

      key            An attribute name, e.g. "cn".

      reverse        True to sort in reverse collation order.

      matchRule      The object ID (OID) of a matching rule used for
                      collation. If the object will be used to request
                      server-side sorting of search results, it should

Expires April 8, 2000                                        [Page 63]

JAVA LDAP API                                             October 1999

                      be the OID of a matching rule known to be
                      supported by that server.

5.26.2 getKey

   public String getKey()

   Returns the attribute to be used for collation.

5.26.3 getReverse

   public boolean getReverse()

   Returns true if the sort key specifies reverse-order sorting.

5.26.4 getMatchRule

   public String getMatchRule()

   Returns the OID to be used as matching rule, or null if none is to be
   used.

5.27 public class LDAPUrl

   Encapsulates parameters of an LDAP Url query, as defined in [7].  An
   LDAPUrl object can be passed to LDAPConnection.search to retrieve
   search results.

5.27.1 Constructors

   public LDAPUrl(String url) throws MalformedURLException

   Constructs a URL object with the specified string as URL.

   public LDAPUrl(String host,
                  int port,
                  String dn)

   Constructs a URL object with the specified host, port, and DN. This
   form is used
   to create URL references to a particular object in the directory.

   public LDAPUrl(String host,
                  int port,

Expires April 8, 2000                                        [Page 64]

JAVA LDAP API                                             October 1999

                  String dn,
                  String attrNames[],
                  int scope,
                  String filter)

   Constructs a full-blown LDAP URL to specify an LDAP search operation.

   Parameters are:

      url            An explicit URL string, e.g.
                      "ldap://ldap.acme.com:80/o=Ace%20Industry,c=us?cn
                      ,sn?sub?(objectclass=inetOrgPerson)".

      host           Host name of LDAP server, or null for "nearest
                      X.500/LDAP".

      port           Port number for LDAP server (use
                      LDAPConnection.DEFAULT_PORT for default port).

      dn             Distinguished name of object to fetch.

      attrNames      Names of attributes to retrieve. null for all
                      attributes.

      scope          Depth of search (in DN namespace). Use one of
                      SCOPE_BASE, SCOPE_ONE, SCOPE_SUB from LDAPv2.

      filter         Search filter specifying the search criteria, as
                      defined in [3].

5.27.2 decode

   public static String decode(String URLEncoded) throws
   MalformedURLException

   Decodes a URL-encoded string. Any occurences of %HH are decoded to
   the hex value represented. However, this method does NOT decode "+"
   into " ". See [9] for details on URL encoding/decoding.

   Parameters are:

      URLEncoded     String to decode.

5.27.3 encode

   public static String encode(String toEncode)

   Encodes an arbitrary string. Any illegal characters are encoded as
   %HH.  However, this method does NOT encode " " into "+".

Expires April 8, 2000                                        [Page 65]

JAVA LDAP API                                             October 1999

   Parameters are:

      toEncode       String to encode.

5.27.4 getAttributes

   public String[] getAttributeArray()

   Returns an array of attribute names specified in the URL.

5.27.5 getAttributes

   public Enumeration getAttributes()

   Returns an Enumerator for the attribute names specified in the URL.

5.27.6 getDN

   public String getDN()

   Returns the distinguished name encapsulated in the URL.

5.27.7 getFilter

   public String getFilter()

   Returns the search filter [7], or the default filter -
   (objectclass=*) - if none was specified.

5.27.8 getHost

   public String getHost()

   Returns the host name of the LDAP server to connect to.

5.27.9 getPort

   public int getPort()

   Returns the port number of the LDAP server to connect to.

5.27.10 getUrl

   public String getUrl()

Expires April 8, 2000                                        [Page 66]

JAVA LDAP API                                             October 1999

   Returns a valid string representation of this LDAP URL.

5.28 public interface LDAPv2

   As a mechanism to support planned and future LDAP protocol
   extensions, functionality is defined in an interface - LDAPv2,
   corresponding to version 2 of the LDAP protocol. LDAPConnection must
   implement at least LDAPv2, and may implement LDAPv3.  Applications
   can test for support of these protocol levels in a given package with
   the instanceof operator.

5.28.1 abandon

   public void abandon(LDAPSearchResults results) throws LDAPException

   Notifies the server to not send additional results associated with
   this LDAPSearchResults object, and discards any results already
   received.

   Parameters are:

      results        An object returned from a search.

   public void add(LDAPEntry entry,
                   LDAPConstraints cons)
                   throws LDAPException

   Adds an entry to the directory.

   Parameters are:

      entry          LDAPEntry object specifying the distinguished
                      name and attributes of the new entry.

      cons           Constraints specific to the operation.

5.28.2 bind

   public void bind(String dn,
                    String passwd)
                    throws LDAPException

   Authenticates to the LDAP server (that the object is currently
   connected to) using the specified name and password.  If the object
   has been disconnected from an LDAP server, this method attempts to
   reconnect to the server. If the object had already authenticated, the
   old authentication is discarded.

Expires April 8, 2000                                        [Page 67]

JAVA LDAP API                                             October 1999

   Parameters are:

      dn             If non-null and non-empty, specifies that the
                      connection and all operations through it should
                      be authenticated with dn as the distinguished
                      name.

      passwd         If non-null and non-empty, specifies that the
                      connection and all operations through it should
                      be authenticated with dn as the distinguished
                      name and passwd as password.

5.28.3 compare

   public boolean compare(String dn,
                          LDAPAttribute attr)
                          throws LDAPException

   public boolean compare(String dn,
                          LDAPAttribute attr,
                          LDAPConstraints cons)
                          throws LDAPException

   Checks to see if an entry contains an attribute with a specified
   value.  Returns true if the entry has the value, and false if the
   entry does not have the value or the attribute.

   Parameters are:

      dn             The distinguished name of the entry to use in the
                      comparison.

      attr           The attribute to compare against the entry. The
                      method checks to see if the entry has an
                      attribute with the same name and value as this
                      attribute.

      cons           Constraints specific to the operation.

5.28.4 connect

   public void connect(String host,
                       int port)
                       throws LDAPException

   Connects to the specified host and port. If this LDAPConnection
   object represents an open connection, the connection is closed first
   before the new connection is opened.  At this point there is no
   authentication, and any operations will be conducted as an anonymous
   client.

Expires April 8, 2000                                        [Page 68]

JAVA LDAP API                                             October 1999

   public void connect(String host,
                       int port,
                       String dn,
                       String passwd)
                       throws LDAPException

   Connects to the specified host and port and uses the specified DN and
   password to authenticate to the server. If this LDAPConnection object
   represents an open connection, the connection is closed first before
   the new connection is opened. This is equivalent to connect(host,
   port) followed by bind(dn, passwd).

   Parameters are:

      host           Contains a hostname or dotted string representing
                      the IP address of a host running an LDAP server
                      to connect to. Alternatively, it may contain a
                      list of host names, space-delimited.  Each host
                      name may include a trailing colon and port
                      number.  In the case where more than one host
                      name is specified, each host name in turn will be
                      contacted until a connection can be established.
                      Examples:

         "directory.knowledge.com"
         "199.254.1.2"
         "directory.knowledge.com:1050 people.catalog.com 199.254.1.2"

      port           Contains the TCP or UDP port number to connect to
                      or contact. The default LDAP port is 389. "port"
                      is ignored for any host name which includes a
                      colon and port number.

      dn             If non-null and non-empty, specifies that the
                      connection and all operations through it should
                      be authenticated with dn as the distinguished
                      name.

      passwd         If non-null and non-empty, specifies that the
                      connection and all operations through it should
                      be authenticated with dn as the distinguished
                      name and passwd as password.

5.28.5 delete

   public void delete(String dn) throws LDAPException

   public void delete(String dn,
                      LDAPConstraints cons)

Expires April 8, 2000                                        [Page 69]

JAVA LDAP API                                             October 1999

                      throws LDAPException

   Deletes the entry for the specified DN from the directory.

   Parameters are:

      dn             Distinguished name of the entry to modify.

      cons           Constraints specific to the operation.

5.28.6 disconnect

   public void disconnect() throws LDAPException

   Disconnects from the LDAP server. Before the object can perform LDAP
   operations again, it must reconnect to the server by calling connect.

5.28.7 getOption

   public Object getOption(int option) throws LDAPException

   Returns the value of the specified option for this object.

   Parameters are:

      option         See LDAPConnection.setOption for a description of
                      valid options.

5.28.8 modify

   public void modify(String dn,
                      LDAPModification mod)
                      throws LDAPException

   public void modify(String dn,
                      LDAPModification mod,
                      LDAPConstraints cons)
                      throws LDAPException

   Makes a single change to an existing entry in the directory (for
   example, changes the value of an attribute, adds a new attribute
   value, or removes an existing attribute value).

   The LDAPModification object specifies both the change to be made and
   the LDAPAttribute value to be changed.

Expires April 8, 2000                                        [Page 70]

JAVA LDAP API                                             October 1999

   public void modify(String dn,
                      LDAPModificationSet mods)
                      throws LDAPException

   public void modify(String dn,
                      LDAPModificationSet mods,
                      LDAPConstraints cons)
                      throws LDAPException

   Makes a set of changes to an existing entry in the directory (for
   example, changes attribute values, adds new attribute values, or
   removes existing attribute values).

   Parameters are:

      dn             Distinguished name of the entry to modify.

      mod            A single change to be made to the entry.

      mods           A set of changes to be made to the entry.

      cons           Constraints specific to the operation.

5.28.9 read

   public LDAPEntry read(String dn) throws LDAPException

   Reads the entry for the specified distiguished name (DN) and
   retrieves all attributes for the entry.

   public LDAPEntry read(String dn,
                         LDAPSearchConstraints cons)
                         throws LDAPException

   Reads the entry for the specified distiguished name (DN) and
   retrieves all attributes for the entry.

   public LDAPEntry read(String dn,
                         String attrs[])
                         throws LDAPException

   Reads the entry for the specified distinguished name (DN) and
   retrieves only the specified attributes from the entry.

   Parameters are:

      dn             Distinguished name of the entry to retrieve.

      cons           Constraints specific to the operation.

Expires April 8, 2000                                        [Page 71]

JAVA LDAP API                                             October 1999

      attrs          Names of attributes to retrieve.

5.28.10 rename

   public void rename(String dn,
                      String newRdn,
                      boolean deleteOldRdn)
                      throws LDAPException

   public void rename(String dn,
                      String newRdn,
                      boolean deleteOldRdn,
                      LDAPConstraints cons)
                      throws LDAPException

   Renames an existing entry in the directory.

   Parameters are:

      dn             Current distinguished name of the entry.

      newRdn         New relative distinguished name for the entry.

      deleteOldRdn   If true, the old name is not retained as an
                      attribute value.

      cons           Constraints specific to the operation.

5.28.11 search

   public LDAPSearchResults search(String base,
                                   int scope,
                                   String filter,
                                   String attrs[],
                                   boolean typesOnly)
                                   throws LDAPException

   Performs the search specified by the parameters.

   public LDAPSearchResults search(String base,
                                   int scope,
                                   String filter,
                                   String attrs[],
                                   boolean typesOnly,
                                   LDAPSearchConstraints cons)
                                   throws LDAPException

   Performs the search specified by the parameters, also allowing

Expires April 8, 2000                                        [Page 72]

JAVA LDAP API                                             October 1999

   specification of constraints for the search (such as the maximum
   number of entries to find or the maximum time to wait for search
   results).

   As part of the search constraints, the function allows specifying
   whether or not the results are to be delivered all at once or in
   smaller batches. If specified that the results are to be delivered in
   smaller batches, each iteration blocks only until the next batch of
   results is returned.

   public static LDAPSearchResults search(LDAPUrl toGet)
                                          throws LDAPException

   public static LDAPSearchResults search(LDAPUrl toGet,
                                          LDAPSearchConstraints cons)
                                          throws LDAPException

   Performs the search specified by the LDAP URL.

   Parameters are:

      base           The base distinguished name to search from.

      scope          The scope of the entries to search. The following
                      are the valid options:

         LDAPv2.SCOPE_BASE            Search only the base DN

         LDAPv2.SCOPE_ONE             Search only entries under the
                                      base DN

         LDAPv2.SCOPE_SUB             Search the base DN and all
                                      entries
                                       within its subtree

      filter         Search filter specifying the search criteria, as
                      defined in [3].

      attrs          Names of attributes to retrieve.

      typesOnly      If true, returns the names but not the values of
                      the attributes found.  If false, returns the
                      names and values for attributes found.

      toGet          LDAP URL representing the search to run. It may
                      contain host, port, base DN, attributes to
                      return, and a search filter.

      cons           Constraints specific to the search.

Expires April 8, 2000                                        [Page 73]

JAVA LDAP API                                             October 1999

5.28.12 setOption

   public void setOption(int option,
                         Object value)
                         throws LDAPException

   Sets the value of the specified option for this object.

   These options represent the default search constraints for the
   current connection. Some of these options are also propagated through
   the LDAPConstraints, which can be obtained from the connection object
   with the getSearchConstraints method.

   The option that is set here applies to all subsequent searches
   performed through the current connection, unless it is overridden
   with an LDAPConstraints at the time of search.

   To set a constraint only for a particular search, create an
   LDAPConstraints object with the new constraints and pass it to the
   LDAPConnection.search method.

   Parameters are:

      option         One of the following options:

         Option                       Type       Description

         LDAPConnection.DEREF         Integer    Specifies under what
                                                  circumstances the
                                                  object dereferences
                                                  aliases. By default,
                                                  the value of this
                                                  option is
                                                  LDAPConnection.DEREF 
                                                                      _
                                                  NEVER.

                     Legal values for this option are:

                     LDAPConnection.DEREF 
                                         _NEVER   Aliases are never
                                                  dereferenced.

                     LDAPConnection.DEREF_
                                          FINDING aliases are
                                                  dereferenced when
                                                  finding the starting
                                                  point for the search
                                                  (but not when
                                                  searching under that
                                                  starting entry).

Expires April 8, 2000                                        [Page 74]

JAVA LDAP API                                             October 1999

                     LDAPConnection.DEREF_SEARCHING    Aliases are
                                                  dereferenced when
                                                  searching the entries
                                                  beneath the starting
                                                  point of the search
                                                  (but not when finding
                                                  the starting entry).

                     LDAPConnection.DEREF_ALWAYS  Aliases are always
                                                  dereferenced (both
                                                  when finding the
                                                  starting point for
                                                  the search and when
                                                  searching under that
                                                  starting entry).

         LDAPConnection.SIZELIMIT     Integer    Specifies the maximum
                                                  number of search
                                                  results to return. If
                                                  this option is set to
                                                  0, there is no
                                                  maximum limit.

                                                  By default, the value
                                                  of this option is
                                                  1000.

         LDAPConnection.SERVER_TIMELIMIT          Integer      Sets the
                                                  maximum number of
                                                  seconds that the
                                                  server is to wait
                                                  when returning search
                                                  results. The
                                                  parameter is only
                                                  recognized on search
                                                  operations.

                                                  By default, the value
                                                  of this option is 0.

         LDAPConnection.TIMELIMIT     Integer    Specifies the maximum
                                                  number of
                                                  milliseconds to wait
                                                  for results before
                                                  timing out. If this
                                                  option is set to 0,

Expires April 8, 2000                                        [Page 75]

JAVA LDAP API                                             October 1999

                                                  there is no maximum
                                                  time limit. The
                                                  actual granularity of
                                                  the timeout depends
                                                  on the
                                                  implementation.

                                                  By default, the value
                                                  of this option is 0.

         LDAPConnection.REFERRALS     Boolean    Specifies whether or
                                                  not the client
                                                  follows referrals
                                                  automatically. If
                                                  true, the client
                                                  follows referrals
                                                  automatically.  If
                                                  false, an
                                                  LDAPReferralException
                                                  is raised when a
                                                  referral is detected.

                                                  Referrals of any type
                                                  other to an LDAP
                                                  server (i.e. a
                                                  referral URL other
                                                  than
                                                  ldap://something) are
                                                  ignored on automatic
                                                  referral following.

                                                  By default, the value
                                                  of this option is
                                                  false.

         LDAPConnection.REFERRALS_REAUTHENTICATIONLDAPRebind  Specifies
                                                  an object that
                                                  implements the
                                                  LDAPRebind interface.
                                                  A user of the class
                                                  library must define
                                                  this class and the
                                                  getRebindAuthenticati
                                                  on method that will
                                                  be used to get the
                                                  distinguished name
                                                  and password to use
                                                  for authentication.
                                                  If this value is null
                                                  and REFERRALS is

Expires April 8, 2000                                        [Page 76]

JAVA LDAP API                                             October 1999

                                                  true, referrals will
                                                  be followed with
                                                  anonymous (= no)
                                                  authentication.

                                                  By default, the value
                                                  of this option is
                                                  null.

         LDAPConnection.BIND          LDAPBind   Specifies an object
                                                  that can process an
                                                  authentication
                                                  request, overriding
                                                  the default
                                                  authentication
                                                  behavior. This is
                                                  typically used for
                                                  processing
                                                  authentication during
                                                  referral following.

         LDAPConnection.REFERRALS_HOP_LIMIT       Integer
                                                        Specifies the
                                                  maximum number of
                                                  referrals in a
                                                  sequence that the
                                                  client will follow.
                                                  For example, if
                                                  REFERRALS_HOP_LIMIT
                                                  is 5, the client will
                                                  follow no more than 5
                                                  referrals in a row
                                                  when resolving a
                                                  single LDAP request.

                                                  The default value of
                                                  this option is 10.

         LDAPConnection.BATCHSIZE     Integer    Specifies the number
                                                  of search results to
                                                  return at a time. For
                                                  example, if BATCHSIZE
                                                  is 1, enumerating an
                                                  LDAPSearchResults
                                                  will block only until
                                                  one entry is
                                                  available. If it is
                                                  0, enumerating will
                                                  block until all
                                                  entries have been

Expires April 8, 2000                                        [Page 77]

JAVA LDAP API                                             October 1999

                                                  retrieved from the
                                                  server.

                                                  The default value of
                                                  this option is 1.

      value          The value to assign to the option. The value must
                      be the java.lang object wrapper for the
                      appropriate parameter (e.g. boolean->Boolean,
                      int->Integer).

5.29 public interface LDAPv3
                      extends LDAPv2

   LDAPv3 extends LDAPv2 by adding support for features of version 3 of
   the LDAP protocol. LDAPConnection implements at least LDAPv2, and may
   also implement LDAPv3. Applications can test for support of these
   protocol levels in a given package with the instanceof operator.

5.29.1 bind

   public void bind(int version,
                    String dn,
                    String passwd)
                    throws LDAPException

   Authenticates to the LDAP server (that the object is currently
   connected to) using the specified name and password, with the
   specified LDAP protocol version. If the server does not support the
   requested protocol version, an exception is thrown.  If the object
   has been disconnected from an LDAP server, this method attempts to
   reconnect to the server. If the object had already authenticated, the
   old authentication is discarded.

   Parameters are:

      version        LDAP protocol version requested: currently 2 or
                      3.

      dn              If non-null and non-empty, specifies that the
                      connection and all operations through it should
                      be authenticated with dn as the distinguished
                      name.

      passwd         If non-null and non-empty, specifies that the
                      connection and all operations through it should
                      be authenticated with dn as the distinguished
                      name and passwd as password.

Expires April 8, 2000                                        [Page 78]

JAVA LDAP API                                             October 1999

   public void bind(String dn,
                    Properties props,
                    javax.security.auth.callback.CallbackHandler cbh)
                    throws LDAPException

   public void bind(String dn,
                    String[] mechanisms,
                    Hashtable props,
                    javax.security.auth.callback.CallbackHandler cbh)
                    throws LDAPException

   Authenticates to the LDAP server (that the object is currently
   connected to) using the specified name and of a specified set of
   mechanisms. If none of the requested SASL mechanisms is available, an
   exception is thrown.  If the object has been disconnected from an
   LDAP server, this method attempts to reconnect to the server. If the
   object had already authenticated, the old authentication is
   discarded. If mechanisms is null, or if the first version of the
   method is called, the LDAP server will be interrogated for its
   supportedSaslMechanisms attribute of its root DSE. See [5] for a
   discussion of the SASL classes.

   Parameters are:

      dn              If non-null and non-empty, specifies that the
                      connection and all operations through it should
                      be authenticated with dn as the distinguished
                      name.

      mechanisms     An array of IANA-registered SASL mechanisms which
                      the client is willing to use for authentication.

      props          Optional qualifiers for the authentication
                      session, as defined in [5].

      cbh            A class which may be called by the Mechanism
                      Driver to obtain additional information required,
                      such as additional credentials.

5.29.2 connect

   public void connect(int version,
                       String host,
                       int port,
                       String dn,
                       String passwd)
                       throws LDAPException

Expires April 8, 2000                                        [Page 79]

JAVA LDAP API                                             October 1999

   Connects to the specified host and port and uses the specified DN and
   password to authenticate to the server, with the specified LDAP
   protocol version. If the server does not support the requested
   protocol version, an exception is thrown. If this LDAPConnection
   object represents an open connection, the connection is closed first
   before the new connection is opened. This is equivalent to
   connect(host, port) followed by bind(version, dn, passwd).

   Parameters are:

      version        LDAP protocol version requested: currently 2 or
                      3.

      host           Contains a hostname or dotted string representing
                      the IP address of a host running an LDAP server
                      to connect to. Alternatively, it may contain a
                      list of host names, space-delimited.  Each host
                      name may include a trailing colon and port
                      number.  In the case where more than one host
                      name is specified, each host name in turn will be
                      contacted until a connection can be established.
                      Examples:

         "directory.knowledge.com"
         "199.254.1.2"
         "directory.knowledge.com:1050 people.catalog.com 199.254.1.2"

      port           Contains the TCP or UDP port number to connect to
                      or contact. The default LDAP port is 389. "port"
                      is ignored for any host name which includes a
                      colon and port number.

      dn             If non-null and non-empty, specifies that the
                      connection and all operations through it should
                      be authenticated with dn as the distinguished
                      name.

      passwd         If non-null and non-empty, specifies that the
                      connection and all operations through it should
                      be authenticated with dn as the distinguished
                      name and passwd as password.

5.29.3 extendedOperation

   public LDAPExtendedOperation extendedOperation(
                                   LDAPExtendedOperation op )
                                   throws LDAPException

Expires April 8, 2000                                        [Page 80]

JAVA LDAP API                                             October 1999

   Provides a means to access extended, non-mandatory operations offered
   by a particular LDAP version 3 compliant server.

   Returns an operation-specific object, containing an ID and an Octet
   String or BER-encoded value(s).

   Parameters are:

      op             Object which contains an identifier of the
                      extended                    operation, which
                      should be one recognized by the ticular server
                      this client is connected to, and  operation-
                      specific sequence of Octet String or BER-encoded
                      value(s).

5.29.4 getResponseControls

   public LDAPControl[] getResponseControls()

   Returns the latest Server Controls returned by a Directory Server
   with a response to an LDAP request from the current thread, or null
   if the latest response contained no Server Controls.

5.29.5 rename

   public void rename(String dn,
                      String newRdn,
                      String newParentdn,
                      boolean deleteOldRdn)
                      throws LDAPException

   public void rename(String dn,
                      String newRdn,
                      String newParentdn,
                      boolean deleteOldRdn,
                      LDAPConstraints cons)
                      throws LDAPException

   Renames an existing entry in the directory, possibly repositioning it
   in the directory tree.

   Parameters are:

      dn             Current distinguished name of the entry.

      newRdn         New relative distinguished name for the entry.

      newParentdn    Distinguished name of the existing entry which is
                      to be the new parent of the entry.

Expires April 8, 2000                                        [Page 81]

JAVA LDAP API                                             October 1999

      deleteOldRdn   If true, the old name is not retained as an
                      attribute value.

      cons           Constraints specific to the operation.

5.30 Client and Server Controls

   LDAPv3 operations can be extended through the use of controls.
   Controls may be sent to a server or returned to the client with any
   LDAP message. These controls are referred to as server controls. The
   LDAP API also supports a client-side extension mechanism through the
   use of client controls (these controls affect the behavior of the
   LDAP API only and are never sent to a server). A common class is used
   to represent both types of controls - LDAPControl.

   Controls are set and retrieved in LDAPConnection with the setOption
   and getOption methods, using the keys LDAPv3.SERVERCONTROLS and
   LDAPv3.CLIENTCONTROLS.  Either a single LDAPControl or an array may
   be passed, e.g.

      LDAPControl control = new LDAPControl( type, critical, vals );
      ld.setOption( LDAPv3.SERVERCONTROLS, control );
   or
      LDAPControl[] controls = new LDAPControl[2];
      controls[0] = new LDAPControl( type0, critical0, vals0 );
      controls[1] = new LDAPControl( type1, critical1, vals1 );
      ld.setOption( LDAPv3.SERVERCONTROLS, controls );

   Server controls returned to a client as part of the response to an
   operation can be obtained with LDAPv3.getResponseControls().

   Support for specific controls is defined in a package "controls"
   subordinate to the main LDAP package.

6. Security Considerations

   LDAP supports security through protocol-level authentication, using
   clear-text passwords or other more secure mechanisms.  It also
   supports running over TLS, which provides strong security at the
   transport layer.
   This draft does not cover TLS implementations, although it identifies
   a mechanism for supplying one, through the LDAPSocketFactory
   interface.
   An interface to using SASL for configurable authentication and
   session protection is provided, but implementations are outside the
   scope of this document.

7. Acknowledgements

Expires April 8, 2000                                        [Page 82]

JAVA LDAP API                                             October 1999

   The proposed API builds on earlier work done in collaboration with
   Thomas Kwan and Stephan Gudmundson, then of of NCware Technologies
   Corp. It also includes suggestions by Jim Sermersheim of Novell.

8. Bibliography

   [1]  The Directory: Selected Attribute Syntaxes.  CCITT,
        Recommendation X.520.

   [2]  M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory
        Access Protocol: Attribute Syntax Definitions",
        RFC 2252, December 1997

   [3]  T. Howes, "A String Representation of LDAP Search Filters," RFC
        1960, June 1996.

   [4]  S. Kille, "A String Representation of Distinguished Names," RFC
        1779, March 1995.

   [5] R. Weltman, R. Lee, R. Earhart, The Java SASL Application Program
        Interface", Internet Draft draft-weltman-java-sasl-02.txt, June
        1999.

   [6]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
        Protocol (v3)", RFC 2251, December 1997.

   [7]  T. Howes, M. Smith, "An LDAP URL Format", RFC 2255, December
        1997.

   [8]  T. Howes, M. Smith, "The LDAP Application Program Interface",
        Internet Draft draft-ietf-ldapext-ldap-c-api-03.txt, June 1999.

   [9] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource
        Locators (URL)", RFC 1738, December 1994.

   [10] H. Alvestrans, "Tags for the Identification of Languages", RFC
        1766, March 1995.

   [11] R. Weltman, C. Tomlinson, "The Java LDAP Application Program
        Interface Asynchronous Extension", Internet Draft draft-ietf-
        ldapext-ldap-java-api-asynch-ext-02.txt, October 1999.

9. Authors' Addresses

   Rob Weltman
   Netscape Communications Corp.
   501 E. Middlefield Rd.
   Mountain View, CA 94043
   USA

Expires April 8, 2000                                        [Page 83]

JAVA LDAP API                                             October 1999

   +1 650 937-3301
   [email-masked]

   Christine Tomlinson
   Innosoft International, Inc.
   8911 Capital of Texas Highway
   Suite 4140
   Austin, TX  US  78759
   +1 512 231 1600
   [email-masked]

   Mark Smith
   Netscape Communications Corp.
   501 E. Middlefield Rd.
   Mountain View, CA 94043
   USA
   +1 650 937-3477
   [email-masked]

   Tim Howes
   1345 Fairway Drive
   Los Altos, CA 94024
   USA
   +1 650 787-5384
   [email-masked]

Expires April 8, 2000                                        [Page 84]

JAVA LDAP API                                             October 1999

10. Appendix A - Sample java LDAP programs

   import netscape.ldap.*;
   import java.util.*;

   public class SearchJensen {
       public static void main( String[] args )
       {
           LDAPConnection ld = new LDAPConnection();
           try {
               /* Connect to server */
               String MY_HOST = "localhost";
               int MY_PORT = 389;
               ld.connect( MY_HOST, MY_PORT );
                /* authenticate to the directory as nobody */
               /* This is not really necessary if explicit
                  authentication is not desired, because there is
                  already anonymous authentication at connect time */
               ld.bind( "", "" );

               /* search for all entries with surname of Jensen */
               String MY_FILTER = "sn=Jensen";
               String MY_SEARCHBASE = "o=Ace Industry, c=US";

               LDAPSearchConstraints cons = ld.getSearchConstraints();
               /* Setting the batchSize to one will cause the result
                  enumeration below to block on one result at a time,
                  allowing us to update a list or do other things as
                  results come in. */
               /* We could set it to 0 if we just wanted to get all
                  results and were willing to block until then */
               cons.setBatchSize( 1 );
               LDAPSearchResults res = ld.search( MY_SEARCHBASE,
                                                  ld.SCOPE_ONE,
                                                  MY_FILTER,
                                                  null,
                                                  false,
                                                  cons );

               /* Loop on results until finished */
               while ( res.hasMoreElements() ) {

                   /* Next directory entry */
                   LDAPEntry findEntry = (LDAPEntry)res.nextElement();
                   System.out.println( findEntry.getDN() );

                   /* Get the attributes of the entry */

                   LDAPAttributeSet findAttrs =
                                        findEntry.getAttributeSet();
                   Enumeration enumAttrs = findAttrs.getAttributes();
                   System.out.println( "Attributes: " );

Expires April 8, 2000                                        [Page 85]

JAVA LDAP API                                             October 1999

                   /* Loop on attributes */
                   while ( enumAttrs.hasMoreElements() ) {
                       LDAPAttribute anAttr =
                           (LDAPAttribute)enumAttrs.nextElement();
                       String attrName = anAttr.getName();
                       System.out.println( "" + attrName );
                       /* Loop on values for this attribute */
                       Enumeration enumVals = anAttr.getStringValues();
                       while ( enumVals.hasMoreElements() ) {
                           String aVal = (String)enumVals.nextElement();
                           System.out.println( "" + aVal );
                       }
                   }
               }
           }
           catch( LDAPException e ) {
               System.out.println( "Error: " + e.toString() );
           }
           /* Done, so disconnect */
           if ( ld.isConnected() )
               ld.disconnect();
       }
   }

Expires April 8, 2000                                        [Page 86]

JAVA LDAP API                                             October 1999

   import netscape.ldap.*;
   import java.util.*;

   public class ModifyEmail {
       public static void main( String[] args )
       {
           LDAPConnection ld = new LDAPConnection();
           try {
               /* Connect to server */
               String MY_HOST = "localhost";
               int MY_PORT = 389;
               ld.connect( MY_HOST, MY_PORT );

               /* authenticate to the directory as Bab Jensen */
               String MY_NAME = "cn=Barbara Jensen,o=Ace Industry,c=US";
               String MY_PASSWORD = "MysteryLady";
               ld.bind( MY_NAME, MY_PASSWORD );

               /* Prepare to change my email address */
               LDAPAttribute attrEmail =
                       new LDAPAttribute( "mail", "[email-masked]" );
               LDAPModification mod =
                       new LDAPModification( LDAPModification.REPLACE,
                                             attrEmail );

               /* Now modify the entry in the directory */
               ld.modify( MY_NAME, mod );
               System.out.println( "Entry modified"  );

           }
           catch( LDAPException e ) {
               System.out.println( "Error: " + e.toString() );
           }
           /* Done, so disconnect */
           if ( ld.isConnected() )
               ld.disconnect();
       }
   }

Expires April 8, 2000                                        [Page 87]

JAVA LDAP API                                             October 1999

   import netscape.ldap.*;
   import java.util.*;

   public class ShowSchema {
       public static void main( String[] args )
       {
           LDAPConnection ld = new LDAPConnection();
           try {
               /* Connect to server */
               String MY_HOST = "localhost";
               int MY_PORT = 389;
               ld.connect( MY_HOST, MY_PORT );

               /* Fetch the schema (anonymous is okay for reading) */
               LDAPSchema schema = new LDAPSchema();
               schema.fetchSchema( ld );

               /* What is the definition of "userPassword"? */
               LDAPAttributeSchema a =
                                 schema.getAttribute( "userpassword" );
               if ( a != null ) {
                  String syntax = a.getSyntaxString();
                  String syntaxString = "string";
                  if ( syntax.equals(BINARY_SYNTAX) )
                      syntaxString = "binary";
                  else if (syntax.equals(INTEGER_SYNTAX) )
                      syntaxString = "integer";
                  String single = "multi-valued";
                  if ( a.isSingleValued() )
                      single = "single-valued";
                  System.out.println( "userPassword. " +
                                      "OID = " + a.getID() +
                                      ", type = " + syntaxString +
                                      ", " + single );
               );

               /* What are the possible attributes for "person"? */
               LDAPObjectClassSchema o =
                                 schema.getObjectClass( "person" );
               if ( o != null ) {
                  Enumeration required = o.getRequiredAttributes();
                  Enumeration optional = o.getOptionalAttributes();
                  System.out.println(
                              "Required attributes for person:" );
                  while( required.hasMoreElements() )
                      System.out.println( "  " +
                              (String)required.nextElement() );
                  System.out.println(
                              "Optional attributes for person:" );
                  while(optional.hasMoreElements() )
                      System.out.println( "  " +
                              (String) optional.nextElement() );

Expires April 8, 2000                                        [Page 88]

JAVA LDAP API                                             October 1999

               );

           } catch( LDAPException e ) {
               System.out.println( "Error: " + e.toString() );
           }
           /* Done, so disconnect */
           if ( ld.isConnected() )
               ld.disconnect();
       }
       protected static final String BINARY_SYNTAX =
                                     "1.3.6.1.4.1.1466.115.121.1.5";
       protected static final String INTEGER_SYNTAX =
                                     "1.3.6.1.4.1.1466.115.121.1.27";
   }

11. Appendix B - Changes from draft-ietf-ldapext-ldap-java-api-07.txt

11.1 LDAPAttributeSchema

   Removed getAliases() because it is already defined in the superior
   class LDAPSchemaElement.

11.2 LDAPConnection

   Added getAuthenticationMethod() (5.6.5).

12. Appendix C - Changes from draft-ietf-ldapext-ldap-java-api-06.txt

12.1 LDAPAttributeSchema

   Added a constructor that takes the attribute syntax as a String, an
   optional superior attribute type, and an optional list of aliases
   (5.2.1). Removed previous constructor.
   Added getSuperior() (5.2.3) and getSyntaxString() (5.2.2).

12.2 LDAPConnection

   Added getInputStream() (5.6.8) getOutputStream() (5.6.9),
   setInputStream() (5.6.20), and setOutputStream() (5.6.21). They are
   used when establishing a security layer with SASL, and may also be
   used to interpose a proxy.

12.3 LDAPDN

   Added equals() (5.9.1).

Expires April 8, 2000                                        [Page 89]

JAVA LDAP API                                             October 1999

12.4 LDAPException

   Added additional error codes defined in [8] (5.13).

12.5 LDAPMatchingRuleSchema

   Added a constructor that takes the attribute syntax as a String and
   an optional list of aliases (5.14.1). Removed previous constructor.

12.6 LDAPObjectClassSchema

   Added a constructor that takes an array of superior object class
   names, a type (ABSTRACT, AUXILIARY, or STRUCTURAL), and an optional
   list of aliases (5.17.1). Removed previous constructor.
   Added getSuperiors() (5.17.2) and getType() (5.17.5). Removed
   getSuperior().

12.7 LDAPSchemaElement

   Added overloaded methods of add, remove, and modify which take a DN
   as parameter, for specifying where in the DIT to determine the
   SubschemaSubentry for the modification (5.22.10 - 5.22.12).
   Added getAliases() (5.22.1), getQualifier() (5.22.5),
   getQualiferNames() (5.22.6), isObsolete() (5.22.7), and
   setQualifier() (5.22.9).

13. Appendix D - Changes from draft-ietf-ldapext-ldap-java-api-05.txt

13.1 LDAPConnection

   Distinguished between getConstraints() and getSearchConstraints(),
   and between setConstraints() and setSearchConstraints().

13.2 LDAPConstraints

   LDAPBind and LDAPRebind should not be specified in the same
   constructor. Added setClientControls().

13.3 LDAPSearchConstraints

   LDAPBind and LDAPRebind should not be specified in the same
   constructor.

Expires April 8, 2000                                        [Page 90]

JAVA LDAP API                                             October 1999

13.4 LDAPControl

   newInstance() is now static.

13.5 LDAPv3

   Changed the signature of the bind() methods to match the Java SASL
   Internet Draft [5].

14. Appendix D - Changes from draft-ietf-ldapext-ldap-java-api-04.txt

14.1 LDAPAttribute

   Added getByteValueArray() and getStringValueArray().

14.2 LDAPCompareAttrNames

   Added getLocale() and setLocale().

14.3 LDAPSchemaElement

   Added modify().

14.4 LDAPSchemaElement

   Added fetchSchema(LDAPConnection, String).

15. Appendix E - Changes from draft-ietf-ldapext-ldap-java-api-03.txt

15.1 LDAPBind

   New interface, to support sophisticated reauthentication mechanisms.

15.2 LDAPControl

   Added methods register() and newInstance(), to support dynamic
   registration and instantiation of server response controls.

15.3 LDAPConstraints

Expires April 8, 2000                                        [Page 91]

JAVA LDAP API                                             October 1999

   Separated interface time limit from server search time limit. Moved
   all search-only constraints to LDAPSearchConstraints.

15.4 LDAPRebind

   Reverted back to original name, instead of LDAPReauthentication as it
   was in the previous draft.

15.5 LDAPRebindProc

   Reverted back from LDAPCredentials.

15.6 LDAPSearchConstraints

   Reinstated this class, to represent all constraints applicable to a
   search. LDAPConstraints (which it extends) only represents common
   constraints for all operations.

15.7 LDAPSearchResults

   Added getResponseControls().

15.8 LDAPv2

   Added abandon(). Separated interface time limit from server search
   time limit. Changed authenticate() to bind().

15.9 LDAPv3

   Changed authenticate() to bind().

16. Appendix F - Changes from draft-ietf-ldapext-ldap-java-api-02.txt

16.1 LDAPSearchConstraints

   Renamed to LDAPConstraints, since it can be applied to operations
   other than search.

16.2 LDAPRebind

   Renamed to LDAPReauthentication. Added a definition of its single
   method.

Expires April 8, 2000                                        [Page 92]

JAVA LDAP API                                             October 1999

16.3 LDAPRebindProc

   Renamed to LDAPCredentials.

17. Appendix F - Changes from draft-ietf-ldapext-ldap-java-api-01.txt

17.1 LDAPAttribute

   Added a copy constructor.
   Added support for subtypes, and for language subtypes in particular.

17.2 LDAPAttributeSet

   LDAPAttributeSet implements Cloneable.
   Added getSubset() for subtype support.

17.3 LDAPDN

   Added support for escaping and unescaping an RDN.

17.4 LDAPException

   Added the SASL_BIND_IN_PROGRESS error code.

17.5 LDAPSearchResults

   Added getCount(), to report the number of results returned.

17.6 LDAPConnection

   Added a signature that passes LDAPConstraints to read(LDAPURL).

17.7 LDAPv2

   Added signatures that pass LDAPConstraints to the following methods:
       add()
       compare()
       modify()
       read()
       rename()

17.8 LDAPv3

Expires April 8, 2000                                        [Page 93]

JAVA LDAP API                                             October 1999

   Removed "Preferred Language", because it has been dropped from the
   extension work.
   Added a signature that passes LDAPConstraints to rename().

Expires April 8, 2000                                        [Page 94]