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 getSyntax....................................................18
5.2.3 getSyntaxString..............................................18
5.2.4 getSuperior..................................................18
5.2.5 getAliases...................................................18
5.2.6 isSingleValued...............................................18
5.3 public class LDAPAttributeSet...................................19
5.3.1 Constructors.................................................19
5.3.2 add..........................................................19
5.3.3 clone........................................................19
5.3.4 elementAt....................................................19
5.3.5 getAttribute.................................................19
5.3.6 getAttributes................................................21
5.3.7 getSubset....................................................21
5.3.8 remove.......................................................21
5.3.9 removeElementAt..............................................22
5.3.10 size.........................................................22
5.4 public interface LDAPBind.......................................22
5.4.1 bind.........................................................22
5.5 public class LDAPCompareAttrNames...............................23
5.5.1 Constructors.................................................23
5.5.2 getLocale....................................................24
5.5.3 setLocale....................................................24
5.5.4 isGreater....................................................24
5.6 public class LDAPConnection.....................................24
5.6.1 Constructors.................................................25
5.6.2 clone........................................................25
Expires April 8, 2000 [Page 2]
JAVA LDAP API October 1999
5.6.3 finalize.....................................................25
5.6.4 getAuthenticationDN..........................................26
5.6.5 getAuthenticationPassword....................................26
5.6.6 getHost......................................................26
5.6.7 getInputStream...............................................26
5.6.8 getOutputStream..............................................26
5.6.9 getPort......................................................26
5.6.10 getProperty..................................................27
5.6.11 getConstraints...............................................27
5.6.12 getSearchConstraints.........................................28
5.6.13 getSocketFactory.............................................28
5.6.14 isBound......................................................28
5.6.15 isConnected..................................................28
5.6.16 read.........................................................28
5.6.17 search.......................................................29
5.6.18 setConstraints...............................................29
5.6.19 setInputStream...............................................30
5.6.20 setOutputStream..............................................30
5.6.21 setProperty..................................................30
5.6.22 setSearchConstraints.........................................30
5.6.23 setSocketFactory.............................................30
5.7 public class LDAPConstraints....................................31
5.7.1 Constructors.................................................31
5.7.2 getHopLimit..................................................32
5.7.3 getBindProc..................................................32
5.7.4 getRebindProc................................................33
5.7.5 getReferrals.................................................33
5.7.6 getTimeLimit.................................................33
5.7.7 setHopLimit..................................................33
5.7.8 setBindProc..................................................33
5.7.9 setRebindProc................................................34
5.7.10 setReferrals.................................................34
5.7.11 setTimeLimit.................................................34
5.7.12 getClientControls............................................34
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.................................................35
5.8.2 clone........................................................36
5.8.3 getID........................................................36
5.8.4 getValue.....................................................36
5.8.5 isCritical...................................................36
5.8.6 newInstance..................................................36
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..................................................37
5.9.4 explodeDN....................................................38
5.9.5 explodeRDN...................................................38
5.10 public class LDAPEntry..........................................38
Expires April 8, 2000 [Page 3]
JAVA LDAP API October 1999
5.10.1 Constructors.................................................39
5.10.2 getAttribute.................................................39
5.10.3 getAttributeSet..............................................39
5.10.4 getDN........................................................40
5.11 public class LDAPExtendedOperation..............................40
5.11.1 Constructors.................................................40
5.11.2 getID........................................................40
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.................................................41
5.13.2 errorCodeToString............................................42
5.13.3 getLDAPErrorMessage..........................................42
5.13.4 getLDAPResultCode............................................43
5.13.5 getMatchedDN.................................................43
5.13.6 Error codes..................................................43
5.14 public class LDAPMatchingRuleSchema.............................44
5.14.1 Constructors.................................................45
5.14.2 getAttributes................................................46
5.14.3 getSyntax....................................................46
5.15 public class LDAPModification...................................46
5.15.1 Constructors.................................................46
5.15.2 getAttribute.................................................46
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.....................................50
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.................................................52
5.21.4 getObjectClass...............................................53
Expires April 8, 2000 [Page 4]
JAVA LDAP API October 1999
5.21.5 getMatchingRule..............................................53
5.21.6 getAttributes................................................53
5.21.7 getObjectClasses.............................................53
5.21.8 getMatchingRules.............................................53
5.21.9 getAttributeNames............................................53
5.21.10 getObjectClassNames.........................................53
5.21.11 getMatchingRuleNames........................................53
5.22 public abstract class LDAPSchemaElement.........................54
5.22.1 getAliases...................................................54
5.22.2 getDescription...............................................54
5.22.3 getName......................................................54
5.22.4 getOID.......................................................54
5.22.5 getQualifier.................................................54
5.22.6 getQualifierNames............................................54
5.22.7 isObsolete...................................................55
5.22.8 getValue.....................................................55
5.22.9 setQualifier.................................................55
5.22.10 add.........................................................55
5.22.11 remove......................................................55
5.22.12 modify......................................................56
5.23 public class LDAPSearchConstraints extends LDAPConstraints......56
5.23.1 Constructors.................................................56
5.23.2 getBatchSize.................................................58
5.23.3 getDereference...............................................58
5.23.4 getMaxResults................................................58
5.23.5 getServerTimeLimit...........................................59
5.23.6 setBatchSize.................................................59
5.23.7 setDereference...............................................59
5.23.8 setMaxResults................................................59
5.23.9 setServerTimeLimit...........................................59
5.24 public class LDAPSearchResults..................................60
5.24.1 getCount.....................................................60
5.24.2 getResponseControls..........................................60
5.24.3 hasMoreElements..............................................60
5.24.4 next.........................................................60
5.24.5 nextElement..................................................60
5.24.6 sort.........................................................61
5.25 public interface LDAPSocketFactory..............................61
5.25.1 makeSocket...................................................61
5.26 public class LDAPSortKey........................................62
5.26.1 Constructors.................................................62
5.26.2 getKey.......................................................63
5.26.3 getReverse...................................................63
5.26.4 getMatchRule.................................................63
5.27 public class LDAPUrl............................................63
5.27.1 Constructors.................................................63
5.27.2 decode.......................................................64
5.27.3 encode.......................................................64
5.27.4 getAttributes................................................65
5.27.5 getAttributes................................................65
5.27.6 getDN........................................................65
5.27.7 getFilter....................................................65
Expires April 8, 2000 [Page 5]
JAVA LDAP API October 1999
5.27.8 getHost......................................................65
5.27.9 getPort......................................................65
5.27.10 getUrl......................................................65
5.28 public interface LDAPv2.........................................66
5.28.1 abandon......................................................66
5.28.2 bind.........................................................66
5.28.3 compare......................................................67
5.28.4 connect......................................................67
5.28.5 delete.......................................................68
5.28.6 disconnect...................................................69
5.28.7 getOption....................................................69
5.28.8 modify.......................................................69
5.28.9 read.........................................................70
5.28.10 rename......................................................71
5.28.11 search......................................................71
5.28.12 setOption...................................................73
5.29 public interface LDAPv3.........................................77
5.29.1 bind.........................................................77
5.29.2 connect......................................................78
5.29.3 extendedOperation............................................79
5.29.4 getResponseControls..........................................80
5.29.5 rename.......................................................80
5.30 Client and Server Controls......................................81
6. Security Considerations.........................................81
7. Acknowledgements................................................82
8. Bibliography....................................................82
9. Authors' Addresses..............................................82
10. Appendix A - Sample java LDAP programs..........................84
11. Appendix B - Changes from draft-ietf-ldapext-ldap-java-api-06.txt88
11.1 LDAPAttributeSchema.............................................88
11.2 LDAPConnection..................................................88
11.3 LDAPDN..........................................................88
11.4 LDAPException...................................................88
11.5 LDAPMatchingRuleSchema..........................................88
11.6 LDAPObjectClassSchema...........................................88
11.7 LDAPSchemaElement...............................................89
12. Appendix C - Changes from draft-ietf-ldapext-ldap-java-api-05.txt89
12.1 LDAPConnection..................................................89
12.2 LDAPConstraints.................................................89
12.3 LDAPSearchConstraints...........................................89
12.4 LDAPControl.....................................................89
12.5 LDAPv3..........................................................89
13. Appendix C - Changes from draft-ietf-ldapext-ldap-java-api-04.txt89
13.1 LDAPAttribute...................................................89
13.2 LDAPCompareAttrNames............................................90
13.3 LDAPSchemaElement...............................................90
13.4 LDAPSchemaElement...............................................90
14. Appendix D - Changes from draft-ietf-ldapext-ldap-java-api-03.txt90
14.1 LDAPBind........................................................90
14.2 LDAPControl.....................................................90
14.3 LDAPConstraints.................................................90
14.4 LDAPRebind......................................................90
Expires April 8, 2000 [Page 6]
JAVA LDAP API October 1999
14.5 LDAPRebindProc..................................................90
14.6 LDAPSearchConstraints...........................................90
14.7 LDAPSearchResults...............................................91
14.8 LDAPv2..........................................................91
14.9 LDAPv3..........................................................91
15. Appendix E - Changes from draft-ietf-ldapext-ldap-java-api-02.txt91
15.1 LDAPSearchConstraints...........................................91
15.2 LDAPRebind......................................................91
15.3 LDAPRebindProc..................................................91
16. Appendix F - Changes from draft-ietf-ldapext-ldap-java-api-01.txt91
16.1 LDAPAttribute...................................................91
16.2 LDAPAttributeSet................................................91
16.3 LDAPDN..........................................................92
16.4 LDAPException...................................................92
16.5 LDAPSearchResults...............................................92
16.6 LDAPConnection..................................................92
16.7 LDAPv2..........................................................92
16.8 LDAPv3..........................................................92
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 attrValue[])
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 getSyntax
public int getSyntax()
Returns the type of the attribute - one of cis, ces, binary, int,
telephone, or dn.
5.2.3 getSyntaxString
public String getSyntaxString()
Returns the Unique Object Identifer of the syntax of the attribute in
dotted numerical format.
5.2.4 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.5 getAliases
public String[] getAliases()
Returns the list of additional names by which the attribute may be
known, or null if there are no aliases.
5.2.6 isSingleValued
public boolean isSingleValued()
Returns true if the attribute is single-valued.
Expires April 8, 2000 [Page 18]
JAVA LDAP API October 1999
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.
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)
Expires April 8, 2000 [Page 19]
JAVA LDAP API October 1999
Returns the attribute matching the specified attrName. For example,
getAttribute("cn") returns only the "cn" attribute
getAttribute("cn;lang-en") returns only the "cn;lang-en"
attribute.
In both cases, null is returned if there is no exact match to the
specified attrName.
public LDAPAttribute[] getAttribute(String attrName, String lang)
Returns a single best-match attribute, or none if no match is
available in the entry.
LDAP version 3 allows adding a subtype specification to an attribute
name. "cn;lang-ja", for example, indicates a Japanese language
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.
Expires April 8, 2000 [Page 20]
JAVA LDAP API October 1999
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.
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
Expires April 8, 2000 [Page 21]
JAVA LDAP API October 1999
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
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().
Expires April 8, 2000 [Page 22]
JAVA LDAP API October 1999
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
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.
Expires April 8, 2000 [Page 23]
JAVA LDAP API October 1999
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.
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.
Expires April 8, 2000 [Page 24]
JAVA LDAP API October 1999
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.
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
Expires April 8, 2000 [Page 25]
JAVA LDAP API October 1999
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 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.6 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.7 getInputStream
public InputStream getInputStream()
Returns the stream used by the connection object for receiving data
from the LDAP server.
5.6.8 getOutputStream
public OutputStream getOutputStream()
Returns the stream used by the connection object to send data to the
LDAP server.
5.6.9 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.10 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.11 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.12 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.13 getSocketFactory
public LDAPSocketFactory getSocketFactory()
Returns the LDAPSocketFactory used to establish a connection to a
server.
5.6.14 isBound
public boolean isBound()
Indicates whether the object has authenticated to the connected LDAP
server.
5.6.15 isConnected
public boolean isConnected()
Indicates whether the connection represented by this object is open
at this time.
5.6.16 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.17 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).
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.18 setConstraints
public void setConstraints(LDAPConstraints cons)
Sets the constraints that apply to all operations performed through
this connection (unless a different set of constraints is specified
when calling an operation method).
Note that the setOption method can be used to set individual
constraints (rather than setting the entire set of constraints).
Expires April 8, 2000 [Page 29]
JAVA LDAP API October 1999
5.6.19 setInputStream
public void setInputStream(InputStream stream)
Sets the stream used by the connection object for receiving data from
the LDAP server.
5.6.20 setOutputStream
public void setOutputStream(OutputStream stream)
Sets the stream used by the connection object to send data to the
LDAP server.
5.6.21 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.22 setSearchConstraints
public void setSearchConstraints(LDAPSearchConstraints cons)
Sets the constraints that apply to all searchoperations performed
through this connection (unless a different set of constraints is
specified when calling a search operation method).
Typically, the setSearchConstraints method is used to create a
slightly different set of search constraints to apply to a particular
search.
5.6.23 setSocketFactory
public void setSocketFactory(LDAPSocketFactory factory)
Expires April 8, 2000 [Page 30]
JAVA LDAP API October 1999
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()
Constructs an LDAPConstraints object that specifies the default
set of constraints.
public LDAPConstraints(int msLimit,
boolean doReferrals,
LDAPBind binder,
int hop_limit)
Expires April 8, 2000 [Page 31]
JAVA LDAP API October 1999
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
public int getHopLimit()
Returns the maximum number of hops to follow during automatic
referral following.
5.7.3 getBindProc
Expires April 8, 2000 [Page 32]
JAVA LDAP API October 1999
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.
5.7.8 setBindProc
public void setBindProc(LDAPBind binder)
Specifies the object that will process authentication requests. The
default is null.
Expires April 8, 2000 [Page 33]
JAVA LDAP API October 1999
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 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:
msLimit Maximum milliseconds to wait.
5.7.12 getClientControls
public LDAPControl[] getClientControls()
Returns controls to be used by the interface.
Expires April 8, 2000 [Page 34]
JAVA LDAP API October 1999
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
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
Expires April 8, 2000 [Page 35]
JAVA LDAP API October 1999
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.
5.8.6 newInstance
public static LDAPControl newInstance(byte[] data)
Instantiates a control, given the raw data representing it in an LDAP
message.
Expires April 8, 2000 [Page 36]
JAVA LDAP API October 1999
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.
5.9.3 unescapeRDN
public static String unescapeRDN (String rdn)
Expires April 8, 2000 [Page 37]
JAVA LDAP API October 1999
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.
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.
Expires April 8, 2000 [Page 38]
JAVA LDAP API October 1999
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 attribute matching the specified attrName. See 5.2.4.
for the syntax and semantics.
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
Expires April 8, 2000 [Page 39]
JAVA LDAP API October 1999
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.
vals The operation-specific data of the operation.
5.11.2 getID
public String getID()
Returns the unique identifier of the operation.
Expires April 8, 2000 [Page 40]
JAVA LDAP API October 1999
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.
5.13.1 Constructors
public LDAPException()
Constructs a default exception with no specific error information.
public LDAPException(String message,
int resultCode)
Expires April 8, 2000 [Page 41]
JAVA LDAP API October 1999
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:
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()
Expires April 8, 2000 [Page 42]
JAVA LDAP API October 1999
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
AUTH_METHOD_NOT_SUPPORTED
BUSY
COMPARE_FALSE
COMPARE_TRUE
CONFIDENTIALITY_REQUIRED
CONSTRAINT_VIOLATION
ENTRY_ALREADY_EXISTS
INAPPROPRIATE_AUTHENTICATION
INAPPROPRIATE_MATCHING
INSUFFICIENT_ACCESS_RIGHTS
Expires April 8, 2000 [Page 43]
JAVA LDAP API October 1999
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
NO_RESULTS_RETURNED
PARAM_ERROR
REFERRAL_LIMIT_EXCEEDED
SERVER_DOWN
USER_CANCELLED
5.14 public class LDAPMatchingRuleSchema
extends LDAPSchemaElement
Expires April 8, 2000 [Page 44]
JAVA LDAP API October 1999
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.
aliases Optional list of additional names by which the
matching rule may be known; null if there are
no aliases.
rawMatchingRule The raw String value returned on a Directory
query for "matchingRule".
rawMatchingRuleUse The raw String value returned on a Directory
query for "matchingRuleUse".
Expires April 8, 2000 [Page 45]
JAVA LDAP API October 1999
5.14.2 getAttributes
public String[] getAttributes()
Returns the OIDs of the attributes to which this rule applies.
5.14.3 getSyntax
public int getSyntax()
Returns the type of the matching rule - one of cis, ces, binary, int,
telephone, or dn.
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.
5.15.2 getAttribute
public LDAPAttribute getAttribute()
Returns the attribute (possibly with values) to be modified.
Expires April 8, 2000 [Page 46]
JAVA LDAP API October 1999
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.
Parameters are:
index Index of the modification to get.
Expires April 8, 2000 [Page 47]
JAVA LDAP API October 1999
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,
String[] optional,
int type,
String[] aliases)
Expires April 8, 2000 [Page 48]
JAVA LDAP API October 1999
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()
Returns a list of attributes required of an entry with this object
class.
Expires April 8, 2000 [Page 49]
JAVA LDAP API October 1999
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.
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()
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.
Expires April 8, 2000 [Page 50]
JAVA LDAP API October 1999
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)
Parameters are:
message The additional error information.
resultCode The result code returned
serverMessage Error message specifying additional information
from the server.
Expires April 8, 2000 [Page 51]
JAVA LDAP API October 1999
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()
5.21.2 fetchSchema
public void fetchSchema(LDAPConnection ld) throws LDAPException
Retrieves the entire schema from a Directory Server. The fetchSchema
methods are the only methods that interact with a Directory Server.
The other methods access information acquired through fetchSchema.
public void fetchSchema(LDAPConnection ld,
String dn) throws LDAPException
Retrieves the schema in effect at a particular entry in the Directory
Server.
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.
Expires April 8, 2000 [Page 52]
JAVA LDAP API October 1999
5.21.4 getObjectClass
public LDAPObjectClassSchema getObjectClass()
Returns a particular object class definition, or null if not found.
5.21.5 getMatchingRule
public LDAPMatchingRuleSchema getMatchingRule()
Returns a particular matching rule definition, or null if not found.
5.21.6 getAttributes
public Enumeration getAttributes()
Returns an enumeration of attribute definitions.
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
Expires April 8, 2000 [Page 53]
JAVA LDAP API October 1999
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.
5.22.2 getDescription
public String getDescription()
Returns the description of the element.
5.22.3 getName
public String getName()
Returns the name of the element.
5.22.4 getOID
public String getOID()
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]).
5.22.6 getQualifierNames
public Enumeration getQualifierNames()
Expires April 8, 2000 [Page 54]
JAVA LDAP API October 1999
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].
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]).
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 store the schema change in.
5.22.11 remove
public void remove(LDAPConnection ld) throws LDAPException
Expires April 8, 2000 [Page 55]
JAVA LDAP API October 1999
public void remove(LDAPConnection ld, String dn) throws LDAPException
Removes the definition from a Directory. An exception is thrown if
the definition can't be removed.
Parameters are:
ld An open connection to a Directory Server.
Typically the connection must have been
authenticated to remove a schema definition.
dn Entry at which to determine the SubschemaSubentry
to store the schema change in.
5.22.12 modify
public void modify(LDAPConnection ld
LDAPAttributeSchema newValue) throws LDAPException
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.
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()
Expires April 8, 2000 [Page 56]
JAVA LDAP API October 1999
Constructs an LDAPSearchConstraints object that specifies the default
set of search constraints.
public LDAPSearchConstraints(int msLimit,
int serverTimeLimit,
int dereference,
int maxResults,
boolean doReferrals,
int batchSize,
LDAPBind binder,
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.
serverTimeLimitMaximum 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).
Expires April 8, 2000 [Page 57]
JAVA LDAP API October 1999
batchSize Specify the number of results to block on during
enumeration. 0 means to block until all results
are in (1 by default).
binder Custom authentication processor, called when the
LDAPConnection needs to authenticate, typically
on following a referral. null may be specified to
indicate default authentication processing.
reauth Specifies an object of the class that implements
the LDAPRebind interface. The object will be used
when the client follows referrals automatically.
The object provides a method for getting the
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.
Expires April 8, 2000 [Page 58]
JAVA LDAP API October 1999
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
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)
Expires April 8, 2000 [Page 59]
JAVA LDAP API October 1999
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
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()
Expires April 8, 2000 [Page 60]
JAVA LDAP API October 1999
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.
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
Expires April 8, 2000 [Page 61]
JAVA LDAP API October 1999
establish TLS and SASL authentication in the java environment have
been standardized.
Parameters are:
host Contains a hostname or dotted string representing
the IP address of a host running an LDAP server
to connect to.
port Contains the TCP or UDP port number to connect to
or contact. The default LDAP port is 389.
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".
Expires April 8, 2000 [Page 62]
JAVA LDAP API October 1999
reverse True to sort in reverse collation order.
matchRule The object ID (OID) of a matching rule used for
collation. If the object will be used to request
server-side sorting of search results, it should
be the OID of a matching rule known to be
supported by that server.
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 with the specified host, port, and DN. This form is used
to create URL references to a particular object in the directory.
Expires April 8, 2000 [Page 63]
JAVA LDAP API October 1999
public LDAPUrl(String host,
int port,
String dn,
String attrNames[],
int scope,
String filter)
Constructs a full-blown LDAP URL to specify an LDAP search operation.
Parameters are:
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.
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 64]
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 65]
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 66]
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
Expires April 8, 2000 [Page 67]
JAVA LDAP API October 1999
client.
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,
Expires April 8, 2000 [Page 68]
JAVA LDAP API October 1999
LDAPConstraints cons)
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 69]
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.
Expires April 8, 2000 [Page 70]
JAVA LDAP API October 1999
cons Constraints specific to the operation.
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
Expires April 8, 2000 [Page 71]
JAVA LDAP API October 1999
Performs the search specified by the parameters, also allowing
specification of constraints for the search (such as the maximum
number of entries to find or the maximum time to wait for search
results).
As part of the search constraints, the function allows specifying
whether or not the results are to be delivered all at once or in
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 72]
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
Expires April 8, 2000 [Page 73]
JAVA LDAP API October 1999
searching under that
starting entry).
LDAPConnection.DEREF_SEARCHING Aliases are
dereferenced when
searching the entries
beneath the starting
point of the search
(but not when finding
the starting entry).
LDAPConnection.DEREF_ALWAYS Aliases are always
dereferenced (both
when finding the
starting point for
the search and when
searching under that
starting entry).
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
Expires April 8, 2000 [Page 74]
JAVA LDAP API October 1999
timing out. If this
option is set to 0,
there is no maximum
time limit. The
actual granularity of
the timeout depends
on the
implementation.
By default, the value
of this option is 0.
LDAPConnection.REFERRALS Boolean Specifies whether or
not the client
follows referrals
automatically. If
true, the client
follows referrals
automatically. If
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.
Expires April 8, 2000 [Page 75]
JAVA LDAP API October 1999
If this value is null
and REFERRALS is
true, referrals will
be followed with
anonymous (= no)
authentication.
By default, the value
of this option is
null.
LDAPConnection.BIND LDAPBind Specifies an object
that can process an
authentication
request, overriding
the default
authentication
behavior. This is
typically used for
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
Expires April 8, 2000 [Page 76]
JAVA LDAP API October 1999
block until all
entries have been
retrieved from the
server.
The default value of
this option is 1.
value The value to assign to the option. The value must
be the java.lang object wrapper for the
appropriate parameter (e.g. boolean->Boolean,
int->Integer).
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
Expires April 8, 2000 [Page 77]
JAVA LDAP API October 1999
be authenticated with dn as the distinguished
name and passwd as password.
public void bind(String dn,
Properties props,
javax.security.auth.callback.CallbackHandler cbh)
throws LDAPException
public void bind(String dn,
String[] mechanisms,
Hashtable props,
javax.security.auth.callback.CallbackHandler cbh)
throws LDAPException
Authenticates to the LDAP server (that the object is currently
connected to) using the specified name and of a specified set of
mechanisms. If none of the requested SASL mechanisms is available, an
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,
Expires April 8, 2000 [Page 78]
JAVA LDAP API October 1999
String passwd)
throws LDAPException
Connects to the specified host and port and uses the specified DN and
password to authenticate to the server, with the specified LDAP
protocol version. If the server does not support the requested
protocol version, an exception is thrown. If this LDAPConnection
object represents an open connection, the connection is closed first
before the new connection is opened. This is equivalent to
connect(host, port) followed by bind(version, dn, passwd).
Parameters are:
version LDAP protocol version requested: currently 2 or
3.
host Contains a hostname or dotted string representing
the IP address of a host running an LDAP server
to connect to. Alternatively, it may contain a
list of host names, space-delimited. Each host
name may include a trailing colon and port
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 )
Expires April 8, 2000 [Page 79]
JAVA LDAP API October 1999
throws LDAPException
Provides a means to access extended, non-mandatory operations offered
by a particular LDAP version 3 compliant server.
Returns an operation-specific object, containing an ID and an Octet
String or BER-encoded value(s).
Parameters are:
op Object which contains an identifier of the
extended operation, which
should be one recognized by the 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.
Expires April 8, 2000 [Page 80]
JAVA LDAP API October 1999
newParentdn Distinguished name of the existing entry which is
to be the new parent of the entry.
deleteOldRdn If true, the old name is not retained as an
attribute value.
cons Constraints specific to the operation.
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.
Expires April 8, 2000 [Page 81]
JAVA LDAP API October 1999
7. Acknowledgements
The proposed API builds on earlier work done in collaboration with
Thomas Kwan and Stephan Gudmundson, then of of NCware Technologies
Corp. It also includes suggestions by Jim Sermersheim of Novell.
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.
Expires April 8, 2000 [Page 82]
JAVA LDAP API October 1999
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
+1 650 937-3301
rweltman@netscape.com
Christine Tomlinson
Innosoft International, Inc.
8911 Capital of Texas Highway
Suite 4140
Austin, TX US 78759
+1 512 231 1600
christine.tomlinson@innosoft.com
Mark Smith
Netscape Communications Corp.
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
+1 650 937-3477
mcs@netscape.com
Tim Howes
1345 Fairway Drive
Los Altos, CA 94024
USA
+1 650 787-5384
timhowes@yahoo.com
Expires April 8, 2000 [Page 83]
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 84]
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 85]
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", "babs@ace.com" );
LDAPModification mod =
new LDAPModification( LDAPModification.REPLACE,
attrEmail );
/* Now modify the entry in the directory */
ld.modify( MY_NAME, mod );
System.out.println( "Entry modified" );
}
catch( LDAPException e ) {
System.out.println( "Error: " + e.toString() );
}
/* Done, so disconnect */
if ( ld.isConnected() )
ld.disconnect();
}
}
Expires April 8, 2000 [Page 86]
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 ) {
int syntax = a.getSyntax();
String syntaxString = "string";
if ( syntax == LDAPAttributeSchema.binary )
syntaxString = "binary";
else if ( syntax == LDAPAttributeSchema.integer )
syntaxString = "integer";
String single = "multi-valued";
if ( a.isSingleValued() )
single = "single-valued";
System.out.println( "userPassword. " +
"OID = " + a.getOID() +
", 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 87]
JAVA LDAP API October 1999
);
} catch( LDAPException e ) {
System.out.println( "Error: " + e.toString() );
}
/* Done, so disconnect */
if ( ld.isConnected() )
ld.disconnect();
}
}
11. Appendix B - Changes from draft-ietf-ldapext-ldap-java-api-06.txt
11.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.4) and getSyntaxString() (5.2.3).
11.2 LDAPConnection
Added getInputStream() (5.6.7) getOutputStream() (5.6.8),
setInputStream() (5.6.19), and setOutputStream() (5.6.20). They are
used when establishing a security layer with SASL, and may also be
used to interpose a proxy.
11.3 LDAPDN
Added equals() (5.9.1).
11.4 LDAPException
Added additional error codes defined in [8] (5.13).
11.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.
11.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.
Expires April 8, 2000 [Page 88]
JAVA LDAP API October 1999
Added getSuperiors() (5.17.2) and getType() (5.17.5). Removed
getSuperior().
11.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).
12. Appendix C - Changes from draft-ietf-ldapext-ldap-java-api-05.txt
12.1 LDAPConnection
Distinguished between getConstraints() and getSearchConstraints(),
and between setConstraints() and setSearchConstraints().
12.2 LDAPConstraints
LDAPBind and LDAPRebind should not be specified in the same
constructor. Added setClientControls().
12.3 LDAPSearchConstraints
LDAPBind and LDAPRebind should not be specified in the same
constructor.
12.4 LDAPControl
newInstance() is now static.
12.5 LDAPv3
Changed the signature of the bind() methods to match the Java SASL
Internet Draft [5].
13. Appendix C - Changes from draft-ietf-ldapext-ldap-java-api-04.txt
13.1 LDAPAttribute
Expires April 8, 2000 [Page 89]
JAVA LDAP API October 1999
Added getByteValueArray() and getStringValueArray().
13.2 LDAPCompareAttrNames
Added getLocale() and setLocale().
13.3 LDAPSchemaElement
Added modify().
13.4 LDAPSchemaElement
Added fetchSchema(LDAPConnection, String).
14. Appendix D - Changes from draft-ietf-ldapext-ldap-java-api-03.txt
14.1 LDAPBind
New interface, to support sophisticated reauthentication mechanisms.
14.2 LDAPControl
Added methods register() and newInstance(), to support dynamic
registration and instantiation of server response controls.
14.3 LDAPConstraints
Separated interface time limit from server search time limit. Moved
all search-only constraints to LDAPSearchConstraints.
14.4 LDAPRebind
Reverted back to original name, instead of LDAPReauthentication as it
was in the previous draft.
14.5 LDAPRebindProc
Reverted back from LDAPCredentials.
14.6 LDAPSearchConstraints
Expires April 8, 2000 [Page 90]
JAVA LDAP API October 1999
Reinstated this class, to represent all constraints applicable to a
search. LDAPConstraints (which it extends) only represents common
constraints for all operations.
14.7 LDAPSearchResults
Added getResponseControls().
14.8 LDAPv2
Added abandon(). Separated interface time limit from server search
time limit. Changed authenticate() to bind().
14.9 LDAPv3
Changed authenticate() to bind().
15. Appendix E - Changes from draft-ietf-ldapext-ldap-java-api-02.txt
15.1 LDAPSearchConstraints
Renamed to LDAPConstraints, since it can be applied to operations
other than search.
15.2 LDAPRebind
Renamed to LDAPReauthentication. Added a definition of its single
method.
15.3 LDAPRebindProc
Renamed to LDAPCredentials.
16. Appendix F - Changes from draft-ietf-ldapext-ldap-java-api-01.txt
16.1 LDAPAttribute
Added a copy constructor.
Added support for subtypes, and for language subtypes in particular.
16.2 LDAPAttributeSet
LDAPAttributeSet implements Cloneable.
Added getSubset() for subtype support.
Expires April 8, 2000 [Page 91]
JAVA LDAP API October 1999
16.3 LDAPDN
Added support for escaping and unescaping an RDN.
16.4 LDAPException
Added the SASL_BIND_IN_PROGRESS error code.
16.5 LDAPSearchResults
Added getCount(), to report the number of results returned.
16.6 LDAPConnection
Added a signature that passes LDAPConstraints to read(LDAPURL).
16.7 LDAPv2
Added signatures that pass LDAPConstraints to the following methods:
add()
compare()
modify()
read()
rename()
16.8 LDAPv3
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 92]
