One document matched: draft-ietf-ldapext-ldap-java-api-14.txt
Differences from draft-ietf-ldapext-ldap-java-api-13.txt
Network Working Group Rob Weltman
INTERNET-DRAFT Coscend Corp.
Intended Category: Standards Track Christine Tomlinson
Sun Microsystems, Inc.
Miodrag Kekic
Netscape Communications Corp.
Steven Sonntag
Novell, Inc.
Jim Sermersheim
Novell, Inc.
Mark Smith
Netscape Communications Corp.
Tim Howes
Loudcloud, Inc.
May 2001
The Java LDAP Application Program Interface
draft-ietf-ldapext-ldap-java-api-14.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 [JAVA] language application program
interface to the Lightweight Directory Access Protocol (LDAP)
[LDAPv3], in the form of a class library.
Conventions Used in this Document
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
Expires October, 2001 [Page 1]
JAVA LDAP API April 2001
in this document are to be interpreted as defined in "Key words for
use in RFCs to Indicate Requirement Levels" [KEYWORDS].
Expires April, 2001 [Page 2]
JAVA LDAP API April 2001
1. Overview...........................................................10
1.1 The LDAP model....................................................10
1.2 The LDAP classes..................................................11
1.3 The LDAP asynchronous methods.....................................12
1.4 Interfaces........................................................12
1.5 Classes...........................................................13
1.6 Exceptions........................................................16
1.7 LDAP API use......................................................16
2. The Java LDAP classes..............................................18
2.1 public class LDAPAttribute........................................18
2.1.1 Constructors....................................................18
2.1.2 addValue........................................................19
2.1.3 getBaseName.....................................................19
2.1.4 getByteValues...................................................19
2.1.5 getByteValueArray...............................................19
2.1.6 getLangSubtype..................................................20
2.1.7 getName.........................................................20
2.1.8 getStringValueArray.............................................20
2.1.9 getStringValues.................................................20
2.1.10 getSubtypes....................................................20
2.1.11 hasSubtype.....................................................21
2.1.12 hasSubtypes....................................................21
2.1.13 removeValue....................................................21
2.1.14 size...........................................................22
2.2 public class LDAPAttributeSchema..................................22
2.2.1 Constructors....................................................22
2.2.2 getSuperior.....................................................23
2.2.3 getEqualityMatchingRule.........................................23
2.2.4 getOrderingMatchingRule.........................................24
2.2.5 getSubstringMatchingRule........................................24
2.2.6 getSyntaxString.................................................24
2.2.7 getUsage........................................................24
2.2.8 isCollective....................................................24
2.2.9 isModifiable....................................................24
2.2.10 isSingleValued.................................................25
2.2.11 Constants of LDAPAttributeSchema...............................25
2.3 public class LDAPAttributeSet.....................................25
2.3.1 Constructors....................................................25
2.3.2 add.............................................................25
2.3.3 clone...........................................................26
2.3.4 elementAt.......................................................26
2.3.5 getAttribute....................................................26
2.3.6 getAttributes...................................................27
2.3.7 getSubset.......................................................27
2.3.8 remove..........................................................28
2.3.9 removeElementAt.................................................28
2.3.10 size...........................................................29
2.4 public interface LDAPBind.........................................29
2.4.1 bind............................................................29
2.5 public class LDAPCompareAttrNames.................................30
2.5.1 Constructors....................................................30
2.5.2 getLocale.......................................................31
Expires April, 2001 [Page 3]
JAVA LDAP API April 2001
2.5.3 isGreater.......................................................31
2.5.4 setLocale.......................................................31
2.6 public class LDAPConnection.......................................31
2.6.1 Constructors....................................................31
2.6.2 abandon.........................................................32
2.6.3 add.............................................................33
2.6.4 addUnsolicitedNotificationListener..............................33
2.6.5 bind............................................................34
2.6.6 clone...........................................................38
2.6.7 compare.........................................................39
2.6.8 connect.........................................................40
2.6.9 delete..........................................................40
2.6.10 disconnect.....................................................41
2.6.11 extendedOperation..............................................41
2.6.12 finalize.......................................................42
2.6.13 getAuthenticationDN............................................42
2.6.14 getAuthenticationMethod........................................42
2.6.15 getConstraints.................................................43
2.6.16 getHost........................................................43
2.6.17 getInputStream.................................................43
2.6.18 getOutputStream................................................43
2.6.19 getPort........................................................43
2.6.20 getProperty....................................................43
2.6.21 getProtocolVersion.............................................44
2.6.22 getResponseControls............................................44
2.6.23 getSaslBindCallbackHandler.....................................45
2.6.24 getSaslBindProperties..........................................45
2.6.25 getSearchConstraints...........................................45
2.6.26 getSocketFactory...............................................45
2.6.27 isBound........................................................45
2.6.28 isConnected....................................................46
2.6.29 isTLS..........................................................46
2.6.30 modify.........................................................46
2.6.31 read...........................................................47
2.6.32 removeUnsolicitedNotificationListener..........................49
2.6.33 rename.........................................................49
2.6.34 search.........................................................50
2.6.35 setConstraints.................................................53
2.6.36 setInputStream.................................................53
2.6.37 setOutputStream................................................53
2.6.38 setProperty....................................................53
2.6.39 setSearchConstraints...........................................54
2.6.40 setSocketFactory...............................................54
2.6.41 startTLS.......................................................54
2.6.42 Constants of LDAPConnection....................................54
2.7 public class public class LDAPConstraints.........................55
2.7.1 Constructors....................................................55
2.7.2 getClientControls...............................................56
2.7.3 getHopLimit.....................................................56
2.7.4 getReferralFollowing............................................56
2.7.5 getServerControls...............................................56
2.7.6 getTimeLimit....................................................57
Expires April, 2001 [Page 4]
JAVA LDAP API April 2001
2.7.7 setClientControls...............................................57
2.7.8 setHopLimit.....................................................57
2.7.9 setReferralFollowing............................................57
2.7.10 setReferralHandler.............................................58
2.7.11 setServerControls..............................................58
2.7.12 setTimeLimit...................................................58
2.8 public class LDAPControl..........................................58
2.8.1 Constructors....................................................59
2.8.2 clone...........................................................59
2.8.3 getID...........................................................59
2.8.4 getValue........................................................59
2.8.5 isCritical......................................................59
2.8.6 register........................................................59
2.8.7 setValue........................................................60
2.9 public class LDAPDITContentRuleSchema.............................60
2.9.1 Constructors....................................................60
2.9.2 getAuxiliaryClasses.............................................61
2.9.3 getOptionalAttributes...........................................62
2.9.4 getPrecludedAttributes..........................................62
2.9.5 getRequiredAttributes...........................................62
2.10 public class LDAPDITStructureRuleSchema..........................62
2.10.1 Constructors...................................................62
2.10.2 getNameForm....................................................63
2.10.3 getRuleID......................................................63
2.10.4 getSuperiors...................................................63
2.11 public class LDAPDN..............................................64
2.11.1 equals.........................................................64
2.11.2 escapeRDN......................................................64
2.11.3 explodeDN......................................................64
2.11.4 explodeRDN.....................................................65
2.11.5 isValid........................................................65
2.11.6 normalize......................................................65
2.11.7 unescapeRDN....................................................65
2.12 public class LDAPEntry...........................................66
2.12.1 Constructors...................................................66
2.12.2 getAttribute...................................................66
2.12.3 getAttributeSet................................................67
2.12.4 getDN..........................................................67
2.13 public interface LDAPEntryComparator.............................67
2.13.1 isGreater......................................................67
2.14 public class LDAPException.......................................68
2.14.1 Constructors...................................................68
2.14.2 errorCodeToString..............................................69
2.14.3 getCause.......................................................70
2.14.4 getLDAPErrorMessage............................................70
2.14.5 getLDAPResultCode..............................................70
2.14.6 getMatchedDN...................................................70
2.14.7 Result codes...................................................70
2.15 public class LDAPExtendedOperation...............................72
2.15.1 Constructors...................................................72
2.15.2 getID..........................................................72
2.15.3 getValue.......................................................72
Expires April, 2001 [Page 5]
JAVA LDAP API April 2001
2.15.4 setValue.......................................................72
2.16 public class LDAPExtendedResponse................................73
2.16.1 getID..........................................................73
2.16.2 getValue.......................................................73
2.17 public interface LDAPListener....................................73
2.17.1 getMessageIDs..................................................73
2.17.2 getResponse....................................................73
2.17.3 isResponseReceived.............................................74
2.17.4 merge..........................................................74
2.18 public class LDAPMatchingRuleSchema..............................74
2.18.1 Constructors...................................................75
2.18.2 getAttributes..................................................76
2.18.3 getSyntaxString................................................76
2.19 public class LDAPMatchingRuleUseSchema...........................76
2.19.1 Constructors...................................................76
2.19.2 getAttributes..................................................77
2.20 public class LDAPMessage.........................................77
2.20.1 getControls....................................................77
2.20.2 getMessageID...................................................77
2.20.3 getType........................................................77
2.21 public class LDAPModification....................................78
2.21.1 Constructors...................................................78
2.21.2 getAttribute...................................................79
2.21.3 getOp..........................................................79
2.21.4 Constants of LDAPModification..................................79
2.22 public class LDAPModificationSet.................................79
2.22.1 Constructors...................................................79
2.22.2 add............................................................79
2.22.3 elementAt......................................................80
2.22.4 remove.........................................................80
2.22.5 removeElementAt................................................80
2.22.6 size...........................................................80
2.23 public class LDAPNameFormSchema..................................80
2.23.1 Constructors...................................................81
2.23.2 getObjectClass.................................................82
2.23.3 getOptionalNamingAttributes....................................82
2.23.4 getRequiredNamingAttributes....................................82
2.24 public class LDAPObjectClassSchema...............................82
2.24.1 Constructors...................................................82
2.24.2 getOptionalAttributes..........................................83
2.24.3 getRequiredAttributes..........................................83
2.24.4 getSuperiors...................................................84
2.24.5 getType........................................................84
2.25 public interface LDAPRebind......................................84
2.25.1 getRebindAuthentication........................................84
2.26 public class LDAPRebindAuth......................................84
2.26.1 Constructors...................................................84
2.26.2 getDN..........................................................85
2.26.3 getPassword....................................................85
2.27 public class LDAPReferralException...............................85
2.27.1 Constructors...................................................85
2.27.2 getFailedReferral..............................................86
Expires April, 2001 [Page 6]
JAVA LDAP API April 2001
2.27.3 getReferrals...................................................86
2.27.4 setFailedReferral..............................................87
2.28 public interface LDAPReferralHandler.............................87
2.29 public class LDAPResponse........................................87
2.29.1 getErrorMessage................................................87
2.29.2 getMatchedDN...................................................87
2.29.3 getReferrals...................................................87
2.29.4 getResultCode..................................................87
2.30 public class LDAPResponseListener................................87
2.30.1 getMessageIDs..................................................88
2.30.2 getResponse....................................................88
2.30.3 isResponseReceived.............................................88
2.30.4 merge..........................................................89
2.31 public class LDAPSchema..........................................89
2.31.1 Constructors...................................................89
2.31.2 fetchSchema....................................................89
2.31.3 getAttribute...................................................90
2.31.4 getAttributeNames..............................................90
2.31.5 getAttributes..................................................90
2.31.6 getDITContentRule..............................................90
2.31.7 getDITContentRuleNames.........................................90
2.31.8 getDITContentRules.............................................90
2.31.9 getDITStructureRule............................................91
2.31.10 getDITStructureRuleNames......................................91
2.31.11 getDITStructureRules..........................................91
2.31.12 getMatchingRule...............................................91
2.31.13 getMatchingRuleNames..........................................91
2.31.14 getMatchingRules..............................................92
2.31.15 getMatchingRuleUse............................................92
2.31.16 getMatchingRuleUseNames.......................................92
2.31.17 getMatchingRuleUses...........................................92
2.31.18 getNameForm...................................................92
2.31.19 getNameFormNames..............................................92
2.31.20 getNameForms..................................................93
2.31.21 getObjectClass................................................93
2.31.22 getObjectClasses..............................................93
2.31.23 getObjectClassNames...........................................93
2.31.24 getSyntax.....................................................93
2.31.25 getSyntaxes...................................................93
2.32 public abstract class LDAPSchemaElement..........................94
2.32.1 add............................................................94
2.32.2 getAliases.....................................................94
2.32.3 getDescription.................................................94
2.32.4 getName........................................................94
2.32.5 getID..........................................................95
2.32.6 getQualifier...................................................95
2.32.7 getQualifierNames..............................................95
2.32.8 getValue.......................................................95
2.32.9 isObsolete.....................................................95
2.32.10 modify........................................................95
2.32.11 remove........................................................96
2.32.12 setQualifier..................................................96
Expires April, 2001 [Page 7]
JAVA LDAP API April 2001
2.33 public class LDAPSearchConstraints...............................97
2.33.1 Constructors...................................................97
2.33.2 getBatchSize...................................................98
2.33.3 getDereference.................................................98
2.33.4 getMaxResults..................................................98
2.33.5 getServerTimeLimit.............................................98
2.33.6 setBatchSize...................................................99
2.33.7 setDereference.................................................99
2.33.8 setMaxResults..................................................99
2.33.9 setServerTimeLimit.............................................99
2.33.10 Constants of LDAPSearchConstraints...........................100
2.34 public class LDAPSearchListener.................................100
2.34.1 getMessageIDs.................................................100
2.34.2 getResponse...................................................100
2.34.3 isComplete....................................................101
2.34.4 isResponseReceived............................................101
2.34.5 merge.........................................................101
2.35 public class LDAPSearchResult...................................101
2.35.1 getEntry......................................................102
2.36 public class LDAPSearchResultReference..........................102
2.36.1 getReferrals..................................................102
2.37 public class LDAPSearchResults..................................102
2.37.1 getCount......................................................102
2.37.2 getResponseControls...........................................102
2.37.3 hasMoreElements...............................................103
2.37.4 next..........................................................103
2.37.5 nextElement...................................................103
2.37.6 sort..........................................................103
2.38 public interface LDAPSocketFactory..............................104
2.38.1 makeSocket....................................................104
2.39 public class LDAPSyntaxSchema...................................104
2.39.1 Constructors..................................................104
2.40 public interface LDAPUnsolicitedNotificationListener............105
2.40.1 messageReceived...............................................105
2.41 public class LDAPUrl............................................105
2.41.1 Constructors..................................................105
2.41.2 decode........................................................107
2.41.3 encode........................................................107
2.41.4 getAttributeArray.............................................107
2.41.5 getAttributes.................................................107
2.41.6 getDN.........................................................107
2.41.7 getExtensions.................................................108
2.41.8 getFilter.....................................................108
2.41.9 getHost.......................................................108
2.41.10 getPort......................................................108
2.41.11 getScope.....................................................108
2.41.12 getUrl.......................................................108
2.41.13 isSecure.....................................................109
3. Implementation Considerations.....................................109
3.1 Client and Server Controls.......................................109
3.2 Referral handling and exceptions.................................109
3.3 Notice of disconnection..........................................111
Expires April, 2001 [Page 8]
JAVA LDAP API April 2001
3.4 Level of compatibility...........................................111
3.5 Invalid responses................................................111
4. Security Considerations...........................................112
5. Acknowledgements..................................................112
6. Bibliography......................................................112
7. Authors' Addresses................................................113
8. Appendix A - Sample java LDAP programs............................115
8.1 Java LDAP programs using synchronous methods.....................115
8.2 Java LDAP programs using asynchronous methods....................120
9. Appendix B - Revision history.....................................125
9.1 Changes from ldap-java-api-13.txt................................125
9.2 Changes from ldap-java-api-12.txt................................126
9.3 Changes from ldap-java-api-11.txt................................127
9.4 Changes from ldap-java-api-10.txt................................130
9.5 Changes from ldap-java-api-09.txt................................131
9.6 Changes from ldap-java-api-08.txt................................131
9.7 Changes from ldap-java-api-07.txt................................132
9.8 Changes from ldap-java-api-06.txt................................132
9.9 Changes from ldap-java-api-05.txt................................133
9.10 Changes from ldap-java-api-04.txt...............................134
9.11 Changes from ldap-java-api-03.txt...............................134
9.12 Changes from ldap-java-api-02.txt...............................135
9.13 Changes from ldap-java-api-01.txt...............................136
Expires April, 2001 [Page 9]
JAVA LDAP API April 2001
1. Overview
The LDAP [LDAPv3] class library is designed to provide powerful, yet
simple, access to LDAP directory services. It defines both
asynchronous and synchronous interfaces to LDAP 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.
1.1 The LDAP model
LDAP is the Lightweight Directory Access Protocol, described in
[LDAPv3]. 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 [X500] 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 directory operations act upon these
values.
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 cn 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
Example company, the DN of her entry might be "cn=Barbara
Jensen,dc=example,dc=com". The DN format used by LDAP is defined in
[DN].
Operations are provided to authenticate, search for and retrieve
information, modify information, and add and delete entries from the
tree. The protocol is also extensible, allowing operations to be
extended by "controls" and new "extended" operations to be defined.
Expires April, 2001 [Page 10]
JAVA LDAP API April 2001
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 server may return a
search reference). The LDAP class library offers the programmer two
options to handle these referrals: the application can receive the
referrals and explicitly issue new requests to the referred-to
servers, or the application can let the library automatically follow
the referrals. In the latter case referrals are followed by default
with anonymous credentials using the protocol level and socket
factory or TLS [TLS][LDAPTLS] of the original connection. If default
behavior is not desired, the application can instruct the library to
follow referrals with an authenticated connection by providing a
reauthentication object to provide credentials for a simple bind, or
the application can provide an object that creates the new
authenticated connection for the API to use when following the
referral.
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, which many LDAPv3 protocol elements and value
encodings use. The integrity of double-byte and other non-ASCII
character sets is fully preserved. If in the future there are
characters added to Unicode which cannot be represented with Java 16-
bit Unicode strings, implementations of the Java LDAP API SHOULD
adopt whatever conventions are introduced into the Java language to
accommodate the characters.
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.
1.2 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, and establish integrity and confidentiality
protective services.
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 LDAPConstraints or
LDAPSearchConstraints).
A synchronous 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
Expires April, 2001 [Page 11]
JAVA LDAP API April 2001
LDAPAttribute objects) returned for that entry. Each attribute can
produce the values found as byte arrays or as Strings.
1.3 The LDAP asynchronous methods
The LDAP protocol provides synchronous as well as asynchronous
directory access methods. All asynchronous methods return listener
objects (either LDAPResponseListener or LDAPSearchListener) and also
take a listener object as input. The listener is a message queue
associated with the request, and it is the responsibility of the
client to read messages out of the queue and process them.
Messages retrieved from an LDAPResponseListener are result objects
derived from LDAPResponse. Messages retrieved from an
LDAPSearchListener are either result objects derived from
LDAPResponse, search results, or search result references.
An asynchronous search conducted by an LDAPConnection object returns
results via the getResponse method of the LDAPSearchListener returned
by the search operation. The getResponse method typically returns an
LDAPSearchResult object which has a getEntry method that returns the
LDAPEntry that represents the search entry.
None of the ancillary asynchronous classes are intended to be
instantiated by a client, so they lack public constructors.
1.4 Interfaces
LDAPEntryComparator An interface to support arbitrary sorting
algorithms for entries returned by a
search operation. The basic Java LDAP
classes include one implementation:
LDAPCompareAttrNames, to sort in
ascending order based on one or more
attribute names.
LDAPListener Common interface for LDAPResponseListener
and LDAPSearchListener. Represents a
queue of incoming asynchronous messages
from the server.
LDAPRebind A programmer desiring to supply
credentials to the default
reauthentication behavior when
automatically following referrals MUST
implement this interface. If LDAPRebind
or LDAPBind are not used, automatically
Expires April, 2001 [Page 12]
JAVA LDAP API April 2001
followed referrals and search references
will use anonymous authentication.
Referrals of any type other than LDAP
URLs [LDAPURL] MAY be chased on automatic
referral following.
LDAPBind This interface allows a programmer to
override the default authentication and
reauthentication behavior when
automatically following referrals and
search references. It is used to specify
the authentication mechanism used on
automatic referral following.
LDAPReferralHandler Interface that is a shared ancestor to
LDAPBind and LDAPRebind.
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.
LDAPUnsolicitedNotificationListener Allows a client to be notified
when unsolicited messages arrive from a
server. Unsolicited messages have a
message ID of 0. An implementation of the
Java LDAP API SHOULD NOT generate
messages with an ID of 0.
1.5 Classes
LDAPAttribute Represents the name and values of one
attribute of a directory entry.
LDAPAttributeSchema Represents a schematic definition of a
particular attribute in a particular
Directory Server.
LDAPAttributeSet A collection of LDAPAttributes.
Expires April, 2001 [Page 13]
JAVA LDAP API April 2001
LDAPCompareAttrNames An implementation of LDAPEntryComparator,
to support sorting of search results by
one or more attributes.
LDAPConnection The central point for interactions with
an LDAP directory.
LDAPConstraints Defines options controlling all
operations.
LDAPControl Sets additional parameters for an LDAP
operation, either on the server or on the
client.
LDAPDITContentRuleSchema Represents a specific DIT content rule in
the directory schema.
LDAPDITStructureRuleSchema Represents a specific DIT structure rule
in the directory schema.
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.
LDAPExtendedResponse The response returned by an LDAP server
on an asynchronous extended operation
request. It extends LDAPResponse.
LDAPMatchingRuleSchema Represents the schematic definition of a
particular matching rule in a particular
Directory Server.
LDAPMatchingRuleUseSchema Represents a specific matching rule use
in the directory schema.
Expires April, 2001 [Page 14]
JAVA LDAP API April 2001
LDAPMessage Base class for LDAP request and response
messages. Subclassed by response messages
used in asynchronous operations.
LDAPModification A single add/delete/replace operation to
an LDAPAttribute.
LDAPModificationSet A collection of LDAPModifications.
LDAPNameFormSchema Represents a specific name form in the
directory schema.
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.
LDAPResponse Represents a message received from an
LDAP server in response to an
asynchronous request. It extends
LDAPMessage.
LDAPResponseListener Low-level mechanism for processing
asynchronous messages received from a
server.
LDAPSchema Represents the schema controlling one or
more entries held by a particular
Directory Server.
LDAPSchemaElement Base class for representing LDAP schema
elements.
LDAPSyntaxSchema Represents a specific syntax definition
in the directory schema.
Expires April, 2001 [Page 15]
JAVA LDAP API April 2001
LDAPSearchConstraints Defines the options controlling search
operations.
LDAPSearchListener Low-level mechanism for queuing
asynchronous search results received from
a server.
LDAPSearchResult A single search result that is in
response to an asynchronous search
operation. It extends LDAPMessage.
LDAPSearchResultReference A continuation reference from an
asynchronous search operation. It extends
LDAPMessage.
LDAPSearchResults The enumerable results of a search
operation.
LDAPUrl Encapsulates parameters of an LDAP Url
query, as defined in [LDAPURL].
1.6 Exceptions
LDAPException General exception, which includes an error
message and an LDAP error code.
LDAPReferralException Derived from LDAPException and contains a list
of URLs corresponding to referrals and/or
search continuations received on an LDAP
operation.
1.7 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.
Expires April, 2001 [Page 16]
JAVA LDAP API April 2001
The synchronous version of LDAPConnection.search() returns an
LDAPSearchResults which can be enumerated to access all entries
found. The asynchronous version of LDAPConnection.search()
returns an LDAPSearchListener, which is used to read the
results of the search. LDAPConnection.read() returns a single
entry.
- Close the connection. The LDAPConnection.disconnect() call
closes the connection.
There are both synchronous and asynchronous versions of the LDAP
protocol operations described in this draft. Synchronous methods do
not return until the operation has completed.
Asynchronous methods take a listener parameter (either
LDAPResponseListener or LDAPSearchListener) and return a listener
object which is used to enumerate the responses from the server. A
loop is typically used to read from the listener object, which blocks
until there is a response available, until the operation has
completed.
An LDAPResponseListener may be shared between operations, for
multiplexing the results. In this case, the object returned on one
operation is passed in to one or more other operations, rather than
passing in null.
For the asynchronous methods, exceptions are raised only for
connection errors. LDAP result messages are converted into
LDAPResponse objects which are to be checked by the client for errors
and referrals, whereas the synchronous methods throw an LDAPException
on result codes other than 0.
To facilitate user feedback during synchronous 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.
Standard Java Enumerations are used to parse synchronous search
results.
Errors result in the throwing of an LDAPException, with a specific
error code and context-specific textual information available.
If null is passed as the value of an LDAPConstraints or
LDAPSearchConstraints parameter to an operation, the default
constraints are used for that operation.
If null is passed as the value of a DN to an operation it is treated
as if it was the empty string.
The API doesn't distinguish between LDAP search continuation
references and LDAP referrals, presenting a unified interface to the
client for handling the two.
Expires April, 2001 [Page 17]
JAVA LDAP API April 2001
Implementations of the API MUST ensure that the LDAPConnection class
is thread-safe. Other classes and methods MAY be thread-safe and the
implementor MUST indicate which classes and methods are thread-safe.
The following sections describe the LDAP classes in more detail.
2. The Java LDAP classes
2.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.
2.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)
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:
Expires April, 2001 [Page 18]
JAVA LDAP API April 2001
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.
2.1.2 addValue
public void addValue(String attrString)
Adds a string value to the attribute.
public 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.
2.1.3 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.
2.1.4 getByteValues
public Enumeration getByteValues()
Returns an enumerator for the values of the attribute in byte[]
format.
2.1.5 getByteValueArray
Expires April, 2001 [Page 19]
JAVA LDAP API April 2001
public byte[][] getByteValueArray()
Returns the values of the attribute as an array of byte[].
2.1.6 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.
2.1.7 getName
public String getName()
Returns the name of the attribute.
2.1.8 getStringValueArray
public String[] getStringValueArray()
Returns the values of the attribute as an array of Strings. This
method should only be called if the attribute values are known to be
strings with values restricted to UTF-8. The returned Strings have
undefined values if the attribute contains values not restricted to
UTF-8.
2.1.9 getStringValues
public Enumeration getStringValues()
Returns an enumerator for the string values of an attribute. This
method should only be called if the attribute values are known to be
strings with values restricted to UTF-8. The returned Strings have
undefined values if the attribute contains values not restricted to
UTF-8.
2.1.10 getSubtypes
public String[] getSubtypes()
public static String[] getSubtypes(String attrName)
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.
Expires April, 2001 [Page 20]
JAVA LDAP API April 2001
Parameters are:
attrName Name of the attribute to extract the subtypes
from.
2.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.
2.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.
2.1.13 removeValue
public void removeValue(String attrString)
Removes a string value from the attribute.
public void removeValue(byte[] attrBytes)
Removes a byte[]-formatted value from the attribute.
Parameters are:
attrString Value of the attribute as a String.
attrBytes Value of the attribute as raw bytes.
Expires April, 2001 [Page 21]
JAVA LDAP API April 2001
2.1.14 size
public int size()
Returns the number of values of the attribute.
2.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 [ATTR] for a description
of attribute representation in LDAP.
2.2.1 Constructors
public LDAPAttributeSchema(String name,
String oid,
String description,
String syntaxString,
boolean single
String superior,
String[] aliases,
boolean obsolete,
String equality,
String ordering,
String substring,
boolean collective,
boolean userMod,
int usage)
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 Object Identifier of the attribute - in dotted
numerical format.
description Optional description of the attribute.
Expires April, 2001 [Page 22]
JAVA LDAP API April 2001
syntaxString Object Identifier of the syntax of the attribute
- in dotted numerical format.
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.
obsolete true if this attribute is obsolete.
equality Object Identifier of the equality matching rule
for the attribute - in dotted numerical format;
MAY be null.
ordering Object Identifier of the ordering matching rule
for the attribute - in dotted numerical format;
MAY be null.
substring Object Identifier of the substring matching rule
for the attribute - in dotted numerical format;
MAY be null.
collective true if this is a collective attribute.
userMod true if the attribute is modifiable by users.
usage One of the following:
USER_APPLICATIONS
DIRECTORY_OPERATION
DISTRIBUTED_OPERATION
DSA_OPERATION
raw The raw String value returned on a Directory
query for "attributetypes".
2.2.2 getSuperior
public String getSuperior()
Returns the name of the attribute type which this attribute derives
from, or null if there is no superior attribute.
2.2.3 getEqualityMatchingRule
Expires April, 2001 [Page 23]
JAVA LDAP API April 2001
public String getEqualityMatchingRule ()
Returns the Object Identifier of the equality matching rule in effect
for this attribute, or null if there is none.
2.2.4 getOrderingMatchingRule
public String getOrderingMatchingRule ()
Returns the Object Identifier of the ordering matching rule in effect
for this attribute, or null if there is none.
2.2.5 getSubstringMatchingRule
public String getSubstringMatchingRule ()
Returns the Object Identifier of the substring matching rule in
effect for this attribute, or null if there is none.
2.2.6 getSyntaxString
public String getSyntaxString()
Returns the Object Identifier of the syntax of the attribute in
dotted numerical format.
2.2.7 getUsage
public int getUsage ()
Returns one of the following:
USER_APPLICATIONS
DIRECTORY_OPERATION
DISTRIBUTED_OPERATION
DSA_OPERATION
2.2.8 isCollective
public boolean isCollective ()
Returns true if the attribute is collective.
2.2.9 isModifiable
public boolean isModifiable ()
Expires April, 2001 [Page 24]
JAVA LDAP API April 2001
Returns true if the attribute is modifiable by users.
2.2.10 isSingleValued
public boolean isSingleValued()
Returns true if the attribute is single-valued.
2.2.11 Constants of LDAPAttributeSchema
The constants correspond to those defined in RFC 2252 [ATTR]:
userApplications, directoryOperation, distributedOperation, and
dSAOperation.
USER_APPLICATIONS (0) An ordinary user attribute
DIRECTORY_OPERATION (1) An operational attribute used for a
directory operation or which holds a
directory specific value
DISTRIBUTED_OPERATION (2) An operational attribute used to hold
server (DSA) information that is shared
among servers holding replicas of the
entry
DSA_OPERATION (3) An operational attribute used to hold
server (DSA) information that is local
to a server
2.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.
2.3.1 Constructors
public LDAPAttributeSet()
Constructs a new set of attributes. This set is initially empty.
2.3.2 add
public void add(LDAPAttribute attr)
Adds the specified attribute to this attribute set.
Expires April, 2001 [Page 25]
JAVA LDAP API April 2001
Parameters are:
attr Attribute to add to this set.
2.3.3 clone
public Object clone()
Returns a deep copy of this attribute set.
2.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.
2.3.5 getAttribute
public LDAPAttribute getAttribute(String attrName)
Returns the attribute matching the specified attrName. For example,
getAttribute("cn") returns only the "cn" attribute
getAttribute("cn;lang-en") returns only the "cn;lang-en"
attribute.
In both cases, null is returned if there is no exact match to the
specified attrName.
public LDAPAttribute getAttribute(String attrName, String lang)
Returns a single best-match attribute, or none if no match is
available in the entry.
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
Expires April, 2001 [Page 26]
JAVA LDAP API April 2001
among localizations, only the base attribute may be stored, whereas
for others there may be varying degrees of specialization.
getAttribute(attrName, lang) returns the subtype that matches
attrName and that best matches lang. If there are subtypes other than
"lang" subtypes included in attrName, e.g. "cn;binary", only
attributes with all of those subtypes are returned. If lang is null
or empty, the method behaves as getAttribute(attrName). If there are
no matching attributes, null is returned.
Example:
Assume the entry contains only the following attributes:
cn;lang-en
cn;lang-ja-JP-kanji
sn
getAttribute( "cn" ) returns null.
getAttribute( "sn" ) returns the "sn" attribute.
getAttribute( "cn", "lang-en-us" ) returns the "cn;lang-en"
attribute.
getAttribute( "cn", "lang-en" ) returns the "cn;lang-en"
attribute.
getAttribute( "cn", "lang-ja" ) returns null.
getAttribute( "sn", "lang-en" ) returns the "sn" attribute.
Parameters are:
attrName The name of an attribute to retrieve, with or without
subtype specification(s). "cn", "cn;phonetic", and cn;binary" are
valid attribute names.
lang A language specification as in [LANG], with
optional subtypes appended using "-" as
separator. "lang-en", "lang-en-us", "lang-ja",
and "lang-ja-JP-kanji" are valid language
specification.
2.3.6 getAttributes
public Enumeration getAttributes()
Returns an enumeration of the attributes in this attribute set.
2.3.7 getSubset
public LDAPAttributeSet getSubset(String subtype)
Expires April, 2001 [Page 27]
JAVA LDAP API April 2001
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
2.3.8 remove
public void remove(String name)
Removes the specified attribute from the set. Subtypes of the
specified attribute are not removed. 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() );
2.3.9 removeElementAt
public void removeElementAt(int index)
throws ArrayIndexOutOfBoundsException
Removes the attribute at the position specified by the index. The
Expires April, 2001 [Page 28]
JAVA LDAP API April 2001
index is 0-based.
Parameters are:
index Index of the attribute to remove.
2.3.10 size
public int size()
Returns the number of attributes in this set.
2.4 public interface LDAPBind
extends LDAPReferralHandler
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 an LDAPConstraints object) or for all operations (through
the LDAPConstraints object associated with the connection).
2.4.1 bind
public LDAPConnection bind(String[] ldapurl, LDAPConnection conn)
throws LDAPReferralException
This method is called by LDAPConnection when a referral is received,
and is responsible for binding to one of the hosts in the list
specified by the ldapurl parameter (which corresponds exactly to the
list of hosts returned in a single referral response). An
implementation may access the host, port, credentials, and other
information in the original LDAPConnection object to decide on an
appropriate authentication mechanism, and/or may interact with a user
or external module. The object implementing LDAPBind creates a new
LDAPConnection object to perform its connect and bind calls. It
returns the new connection when both the connect and bind operations
succeed on one host from the list. The LDAPConnection object referral
following code uses the new LDAPConnection object when it resends the
search request, updated with the new search base and possibly search
filter. An LDAPReferralException is thrown on failure.
Parameters are:
ldapurl List of LDAP server URLs. There is no order
implied by the list.
conn An established connection to an LDAP server.
Expires April, 2001 [Page 29]
JAVA LDAP API April 2001
2.5 public class LDAPCompareAttrNames
implements LDAPEntryComparator
An object of this class supports sorting search results by attribute
name, in ascending or descending order. Sorting is by locale-
sensitive Java String comparison, which may not correspond to the
LDAP ordering rules by which an LDAP server would sort them.
2.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.
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
Expires April, 2001 [Page 30]
JAVA LDAP API April 2001
the length of ascendingFlags is not greater than
or equal to the length of attrNames.
2.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.
2.5.3 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.
2.5.4 setLocale
public void setLocale(Locale locale)
Sets the Locale to be used for sorting.
Parameters are:
locale The Locale to be used for sorting.
2.6 public class LDAPConnection
implements Cloneable
LDAPConnection is the central class that encapsulates the connection
to a Directory Server through the LDAP protocol. 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.
2.6.1 Constructors
Expires April, 2001 [Page 31]
JAVA LDAP API April 2001
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.
2.6.2 abandon
public void abandon(LDAPSearchResults results)
throws LDAPException
public void abandon(LDAPSearchResults results, LDAPConstraints cons)
throws LDAPException
public void abandon(int id)
throws LDAPException
public void abandon(int id, LDAPConstraints cons)
throws LDAPException
public void abandon(LDAPListener listener)
throws LDAPException
public void abandon(LDAPListener listener, LDAPConstraints cons)
throws LDAPException
Either notifies the server to not send additional results associated
with this LDAPSearchResults object, and discards any results already
received, or abandons one or all operations for an asynchronous
response listener.
The application is responsible for not calling this method more than
once with a particular id or LDAPSearchResults.
Parameters are:
results An object returned from a search.
Expires April, 2001 [Page 32]
JAVA LDAP API April 2001
id The ID of the asynchronous operation to abandon.
The ID may be obtained from the response listener
for the operation.
listener Handler returned from an asynchronous request.
All outstanding operations that are managed by
the listener are abandoned.
cons Constraints specific to the operation.
2.6.3 add
public void add(LDAPEntry entry)
throws LDAPException
public void add(LDAPEntry entry,
LDAPConstraints cons)
throws LDAPException
public LDAPResponseListener add(LDAPEntry entry,
LDAPResponseListener listener)
throws LDAPException
public LDAPResponseListener add(LDAPEntry entry,
LDAPResponseListener listener,
LDAPConstraints cons)
throws LDAPException
Adds an entry to the directory.
The application is responsible for not specifying attribute values
which are not valid according to the syntax defined for the
attributes. It is also responsible for including all attributes which
are required for the entry.
Parameters are:
entry LDAPEntry object specifying the distinguished
name and attributes of the new entry.
listener Handler for messages returned from a server in
response to this request. If it is null, a
listener object is created internally.
cons Constraints specific to the operation.
2.6.4 addUnsolicitedNotificationListener
public void addUnsolicitedNotificationListener(
Expires April, 2001 [Page 33]
JAVA LDAP API April 2001
LDAPUnsolicitedNotificationListener listener)
Registers an object to be notified on arrival of an unsolicited
message from a server.
Parameters are:
listener An object to be notified on arrival of an
unsolicited message from a server.
2.6.5 bind
public void bind(String dn,
String passwd)
throws LDAPException
public void bind(String dn,
byte[] passwd)
throws LDAPException
public void bind(String dn,
String passwd,
LDAPConstraints cons,
throws LDAPException
public void bind(String dn,
byte[] passwd,
LDAPConstraints cons,
throws LDAPException
public LDAPResponseListener bind(String dn,
String passwd,
LDAPResponseListener listener)
throws LDAPException
public LDAPResponseListener bind(String dn,
byte[] passwd,
LDAPResponseListener listener)
throws LDAPException
public LDAPResponseListener bind(String dn,
String passwd,
LDAPResponseListener listener,
LDAPConstraints cons)
throws LDAPException
public LDAPResponseListener bind(String dn,
byte[] passwd,
LDAPResponseListener listener,
LDAPConstraints cons)
throws LDAPException
Expires April, 2001 [Page 34]
JAVA LDAP API April 2001
Authenticates with LDAPv3 protocol 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. A bind reconnecting
an interrupted connection will not disassociate existing clones. If
the object had already authenticated, the old authentication is
discarded.
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.
listener Handler for messages returned from a server in
response to this request. If it is null, a
listener object is created internally. It is
recommended that either the synchronous version
of this method is used or that the client blocks
until the listener returns a response.
cons Constraints specific to the operation.
public void bind(int version,
String dn,
String passwd)
throws LDAPException
public void bind(int version,
String dn,
String passwd)
LDAPConstraints cons,
throws LDAPException
public LDAPResponseListener bind(int version,
String dn,
String passwd,
LDAPResponseListener listener)
throws LDAPException
public LDAPResponseListener bind(int version,
String dn,
String passwd,
Expires April, 2001 [Page 35]
JAVA LDAP API April 2001
LDAPResponseListener listener,
LDAPConstraints cons)
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. This API is specifically designed
for use with LDAPv3. Unless the API provides specific support (as
defined in other documents) for other versions of LDAP, version 3
should be used. If the server does not support the requested protocol
version, an exception is thrown. If the object has been disconnected
from an LDAP server, this method attempts to reconnect to the server.
If the object had already authenticated, the old authentication is
discarded.
Parameters are:
version LDAP protocol version requested: currently 2 or
3.
dn If non-null and non-empty, specifies that the
connection and all operations through it SHOULD
be authenticated with dn as the distinguished
name.
passwd If non-null and non-empty, specifies that the
connection and all operations through it SHOULD
be authenticated with dn as the distinguished
name and passwd as password.
listener Handler for messages returned from a server in
response to this request. If it is null, a
listener object is created internally.
cons Constraints specific to the operation.
public void bind(String dn,
String authzId,
Properties props,
javax.security.auth.callback.CallbackHandler cbh)
throws LDAPException
public void bind(String dn,
String authzId,
Properties props,
javax.security.auth.callback.CallbackHandler cbh,
LDAPConstraints cons)
throws LDAPException
Expires April, 2001 [Page 36]
JAVA LDAP API April 2001
public void bind(String dn,
String authzId,
String[] mechanisms,
Hashtable props,
javax.security.auth.callback.CallbackHandler cbh)
throws LDAPException
public void bind(String dn,
String authzId,
String[] mechanisms,
Hashtable props,
javax.security.auth.callback.CallbackHandler cbh,
LDAPConstraints cons)
throws LDAPException
Authenticates to the LDAP server (that the object is currently
connected to) using the specified name and one of a specified set of
mechanisms. If none of the requested SASL [SASL][AUTH][JAVASASL]
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. A SASL bind call() may involved
multiple protocol requests. An attempt to invoke an operation between
bind requests in a multi-stage bind results in an LDAPException with
the result code SASL_BIND_IN_PROGRESS.
Parameters are:
dn The distinguished name to use as the bind name.
This value is not used as either a SASL
authentication nor authorization identity. The
application provides these identities through the
callback handler.
authzId If not null and not empty, an LDAP authzID [AUTH]
to be passed to the SASL layer.
mechanisms An array of IANA-registered SASL mechanisms which
the client is willing to use for authentication.
props Optional qualifiers for the authentication
session.
cbh A class which may be called by the Mechanism
Driver to obtain additional information required,
such as additional credentials.
cons Constraints specific to the operation.
Expires April, 2001 [Page 37]
JAVA LDAP API April 2001
2.6.6 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.
Methods that are global in nature and which affect the source object
are:
addUnsolicitedNotificationListener
bind
connect
disconnect
finalize
removeUnsolicitedNotificationListener
setInputStream
setOutputStream
startTLS
The following methods return data that is from the source object and
is the same for all clones of LDAPConnection:
getAuthenticationDN
getAuthenticationMethod
getHost
getInputStream
getOutputStream
getPort
getProtocolVersion
getSaslBindCallBackHandler
getSaslBindProperties
getSocketFactory
isBound
isConnected
isTLS
The following methods manipulate or retrieve data that is unique to
each clone of LDAPConnection:
Expires April, 2001 [Page 38]
JAVA LDAP API April 2001
getConstraints
getProperty
getResponseControls
getSearchConstraints
setConstraints
setProperty
setResponseControls
setSearchConstraints
2.6.7 compare
public boolean compare(String dn,
LDAPAttribute attr)
throws LDAPException
public boolean compare(String dn,
LDAPAttribute attr,
LDAPConstraints cons)
throws LDAPException
public LDAPResponseListener compare(String dn,
LDAPAttribute attr,
LDAPResponseListener listener)
throws LDAPException
public LDAPResponseListener compare(String dn,
LDAPAttribute attr,
LDAPResponseListener listener,
LDAPConstraints cons)
throws LDAPException
Checks to see if an entry contains an attribute with a specified
value. The synchronous methods return a value of 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.
listener Handler for messages returned from a server in
response to this request. If it is null, a
listener object is created internally.
cons Constraints specific to the operation.
Expires April, 2001 [Page 39]
JAVA LDAP API April 2001
2.6.8 connect
public void connect(String host,
int port)
throws LDAPException
Connects to the specified host and port. If this LDAPConnection
object represents an open connection, the connection is closed first
before the new connection is opened. At this point there is no
authentication, and any operations will be conducted as an anonymous
client.
Parameters are:
host Contains a host identifier consisting of a
hostname, an IPv4 dotted string, or an IPv6
reference [IPv6] representing the IP address of a
host running an LDAP server to connect to.
Alternatively, it may contain a list of host
identifiers, space-delimited. Each host
identifier may include a trailing colon and port
number. In the case where more than one host
identifier is specified, each host identifier in
turn will be contacted until a connection can be
established. Examples:
"directory.example.com"
" 192.0.2.0"
"[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:4389"
"directory.example.com:1050 people.catalog.com 192.0.2.0"
port Contains the TCP port number to connect to or
contact. The default LDAP port is 389. "port" is
ignored for any host identifier which includes a
colon and port number.
2.6.9 delete
public void delete(String dn) throws LDAPException
public void delete(String dn,
LDAPConstraints cons)
throws LDAPException
public LDAPResponseListener delete(String dn,
LDAPResponseListener listener)
throws LDAPException
public LDAPResponseListener delete(String dn,
Expires April, 2001 [Page 40]
JAVA LDAP API April 2001
LDAPResponseListener listener,
LDAPConstraints cons)
throws LDAPException
Deletes the entry for the specified DN from the directory.
Parameters are:
dn Distinguished name of the entry to modify.
listener Handler for messages returned from a server in
response to this request. If it is null, a
listener object is created internally.
cons Constraints specific to the operation.
2.6.10 disconnect
public void disconnect() throws LDAPException
public void disconnect(LDAPConstraints cons) throws LDAPException
Disconnects from the LDAP server. The API implementation sends an
Unbind request to the server with any controls specified by the
LDAPConstraints object before closing the connection. Before the
object can perform LDAP operations again, it MUST reconnect to the
server by calling either connect or bind (bind will attempt to
reconnect).
Parameters are:
cons Constraints to be sent with the unbind request.
2.6.11 extendedOperation
public LDAPExtendedResponse extendedOperation(
LDAPExtendedOperation op )
throws LDAPException
public LDAPExtendedResponse extendedOperation(
LDAPExtendedOperation op,
LDAPConstraints cons )
throws LDAPException
public LDAPResponseListener extendedOperation(
LDAPExtendedOperation op,
LDAPResponseListener listener)
throws LDAPException
Expires April, 2001 [Page 41]
JAVA LDAP API April 2001
public LDAPResponseListener extendedOperation(
LDAPExtendedOperation op,
LDAPConstraints cons,
LDAPResponseListener listener)
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 particular server this client
is connected to, and operation-specific sequence
of Octet String or BER-encoded value(s).
cons Constraints specific to the operation.
2.6.12 finalize
public void finalize() throws LDAPException
Closes the connection if open and releases any other resources held
by the object.
2.6.13 getAuthenticationDN
public String getAuthenticationDN()
Returns the distinguished name (DN) used as the bind name during the
last successful bind operation. null is returned if no authentication
has been performed.
2.6.14 getAuthenticationMethod
public String getAuthenticationMethod()
Returns the method used to authenticate the connection. The return
value is one of the following:
"none" The current authentication state has not been
established by use of the bind operation. This
is the initial state upon connect().
Expires April, 2001 [Page 42]
JAVA LDAP API April 2001
"simple" Simple bind has completed (anonymous,
unauthenticated, or authenticated)
"sasl" The current authentication state was established
by the successful completion of a SASL bind
2.6.15 getConstraints
public LDAPConstraints getConstraints()
Returns a copy of the set of constraints associated with this
connection. These constraints apply to all operations performed
through this connection (unless a different set of constraints is
specified when calling an operation method).
2.6.16 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.
2.6.17 getInputStream
public InputStream getInputStream()
Returns the stream used by the connection object for receiving data
from the LDAP server.
2.6.18 getOutputStream
public OutputStream getOutputStream()
Returns the stream used by the connection object to send data to the
LDAP server.
2.6.19 getPort
public int getPort()
Returns the port number of the LDAP server to which the object is or
was last connected.
2.6.20 getProperty
public Object getProperty(String name) throws LDAPException
Expires April, 2001 [Page 43]
JAVA LDAP API April 2001
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 ("version.sdk") The version of
this SDK, as a
Float data type.
LDAP_PROPERTY_PROTOCOL ("version.protocol") The
highest supported
version of the LDAP
protocol, as a
Float data type.
LDAP_PROPERTY_SECURITY ("version.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.
2.6.21 getProtocolVersion
public int getProtocolVersion ()
Returns the protocol level that the connection is bound to (2 or 3).
2.6.22 getResponseControls
public LDAPControl[] getResponseControls()
Expires April, 2001 [Page 44]
JAVA LDAP API April 2001
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. For asynchronous
requests, the response controls are available in LDAPMessage.
2.6.23 getSaslBindCallbackHandler
public javax.security.auth.callback.CallbackHandler
getSaslBindCallbackHandler()
Returns the callback handler, if any, specified on binding with a
SASL mechanism.
2.6.24 getSaslBindProperties
public Hashtable getSaslBindProperties()
Returns the properties, if any, specified on binding with a SASL
mechanism.
2.6.25 getSearchConstraints
public LDAPSearchConstraints getSearchConstraints()
Returns a copy of the set of search constraints associated with this
connection. These constraints apply to search operations performed
through this connection (unless a different set of constraints is
specified when calling the search operation method). The search
constraints include the base constraints returned by
getConstraints().
2.6.26 getSocketFactory
public LDAPSocketFactory getSocketFactory()
Returns the LDAPSocketFactory used to establish a connection to a
server.
2.6.27 isBound
public boolean isBound()
Indicates whether the object has authenticated to the connected LDAP
server (other than anonymously).
Expires April, 2001 [Page 45]
JAVA LDAP API April 2001
2.6.28 isConnected
public boolean isConnected()
Indicates if the connection represented by this object is open at
this time.
2.6.29 isTLS
public boolean isTLS ()
Indicates the session is currently protected by TLS. The
method provides no indication of the level of protection provided.
2.6.30 modify
public void modify(String dn,
LDAPModification mod)
throws LDAPException
public void modify(String dn,
LDAPModification mod,
LDAPConstraints cons)
throws LDAPException
public LDAPResponseListener modify(String dn,
LDAPModification mod,
LDAPResponseListener listener)
throws LDAPException
public LDAPResponseListener modify(String dn,
LDAPModification mod,
LDAPResponseListener listener,
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.
The application is responsible for specifying attribute values which
are valid according to the syntax defined for the attributes.
public void modify(String dn,
LDAPModificationSet mods)
throws LDAPException
Expires April, 2001 [Page 46]
JAVA LDAP API April 2001
public void modify(String dn,
LDAPModificationSet mods,
LDAPConstraints cons)
throws LDAPException
public LDAPResponseListener modify(String dn,
LDAPModificationSet mods,
LDAPResponseListener listener)
throws LDAPException
public LDAPResponseListener modify(String dn,
LDAPModificationSet mods,
LDAPResponseListener listener,
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).
The application is responsible for specifying attribute values which
are valid according to the syntax defined for the attributes.
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.
listener Handler for messages returned from a server in
response to this request. If it is null, a
listener object is created internally.
cons Constraints specific to the operation.
2.6.31 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
Expires April, 2001 [Page 47]
JAVA LDAP API April 2001
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
public LDAPEntry read(String dn,
String[] attrs,
LDAPSearchConstraints cons)
throws LDAPException
Reads the entry for the specified distinguished name (DN) and
retrieves only the specified attributes from the entry.
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
name and port number, the base distinguished name (DN), the list of
attributes to return, and any extensions.
The method returns the entry specified by the base DN.
Parameters are:
dn Distinguished name of the entry to retrieve.
cons Constraints specific to the operation.
attrs Names of attributes to retrieve.
toGet LDAP URL specifying the entry to read.
If the server does not return exactly one entry, an LDAPException is
thrown with a result code of AMBIGIOUS_RESPONSE.
Expires April, 2001 [Page 48]
JAVA LDAP API April 2001
Note: read is simply a helper method and uses the ldap search
operation to achieve the results. As such, there is no asynchronous
interface.
2.6.32 removeUnsolicitedNotificationListener
public void removeUnsolicitedNotificationListener(
LDAPUnsolicitedNotificationListener listener)
Deregisters an object so that it will no longer be notified on
arrival of an unsolicited message from a server. If the object is
null or was not previously registered for unsolicited notifications,
the method does nothing.
Parameters are:
listener An object to no longer be notified on arrival of
an unsolicited message from a server.
2.6.33 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
public LDAPResponseListener rename(String dn,
String newRdn,
boolean deleteOldRdn,
LDAPResponseListener listener)
throws LDAPException
public LDAPResponseListener rename(String dn,
String newRdn,
boolean deleteOldRdn,
LDAPResponseListener listener,
LDAPConstraints cons)
throws LDAPException
Renames an existing entry in the directory.
public void rename(String dn,
String newRdn,
Expires April, 2001 [Page 49]
JAVA LDAP API April 2001
String newParentdn,
boolean deleteOldRdn)
throws LDAPException
public void rename(String dn,
String newRdn,
String newParentdn,
boolean deleteOldRdn,
LDAPConstraints cons)
throws LDAPException
public LDAPResponseListener rename(String dn,
String newRdn,
boolean deleteOldRdn)
String newParentdn,
LDAPResponseListener listener)
throws LDAPException
public LDAPResponseListener rename(String dn,
String newRdn,
String newParentdn,
boolean deleteOldRdn,
LDAPResponseListener listener,
LDAPConstraints cons)
throws LDAPException
Renames an existing entry or subtree in the directory, possibly
repositioning it
in the directory tree.
Parameters are:
dn Current distinguished name of the entry.
newRdn New relative distinguished name for the entry.
newParentdn Distinguished name of the existing entry which is
to be the new parent of the entry.
deleteOldRdn If true, the old name is not retained as an
attribute value.
listener Handler for messages returned from a server in
response to this request. If it is null, a
listener object is created internally.
cons Constraints specific to the operation.
2.6.34 search
public LDAPSearchResults search(String base,
Expires April, 2001 [Page 50]
JAVA LDAP API April 2001
int scope,
String filter,
String[] attrs,
boolean typesOnly)
throws LDAPException
public LDAPSearchListener search(String base,
int scope,
String filter,
String[] attrs,
boolean typesOnly,
LDAPSearchListener listener)
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
public LDAPSearchListener search(String base,
int scope,
String filter,
String[] attrs,
boolean typesOnly,
LDAPSearchListener listener,
LDAPSearchConstraints cons)
throws LDAPException
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
Performs the search specified by the LDAP URL, returning an
enumerable LDAPSearchResults object.
Expires April, 2001 [Page 51]
JAVA LDAP API April 2001
public static LDAPSearchResults search(LDAPUrl toGet,
LDAPSearchConstraints cons)
throws LDAPException
Perfoms the search specified by the LDAP URL. This method also allows
specifying constraints for the search (such as the maximum number of
entries to find or the maximum time to wait for search results).
When this method is called, a new connection is created
automatically, using the host and port specified in the URL. After
all search results have been received from the server, the method
closes the connection (in other words, it disconnects from the LDAP
server).
As part of the search constraints, a choice can be made as to whether
to have the results delivered all at once or in smaller batches. If
the results are to be delivered in smaller batches, each iteration
blocks only until the next batch of results is returned.
Parameters are:
base The base distinguished name to search from.
scope The scope of the entries to search. The following
are the valid options:
SCOPE_BASE Search only the base DN
SCOPE_ONE Search only entries directly under the base
DN
SCOPE_SUB Search the base DN and all entries within
its subtree
filter Search filter specifying the search criteria, as
defined in [FILTER]. The value null can be passed
to indicate that the filter "(objectclass=*)"
which matches all entries is to be used.
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 specifying the entry to read.
listener Handler for messages returned from a server in
response to this request. If it is null, a
listener object is created internally.
Expires April, 2001 [Page 52]
JAVA LDAP API April 2001
cons Constraints specific to the search.
Note: RFC 2251 [LDAPv3] indicates that extendedResponses on search
requests may be defined in future versions of the LDAP protocol.
There is no support for extendedResponses on search requests in this
version of the Java LDAP API.
2.6.35 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).
2.6.36 setInputStream
public void setInputStream(InputStream stream)
Sets the stream used by the connection object for receiving data from
the LDAP server.
2.6.37 setOutputStream
public void setOutputStream(OutputStream stream)
Sets the stream used by the connection object to send data to the
LDAP server.
2.6.38 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.
Expires April, 2001 [Page 53]
JAVA LDAP API April 2001
2.6.39 setSearchConstraints
public void setSearchConstraints(LDAPSearchConstraints cons)
Sets the constraints that apply to all search operations performed
through this connection (unless a different set of constraints is
specified when calling a search operation method).
Typically, the setSearchConstraints method is used to create a
slightly different set of search constraints to apply to a particular
search.
2.6.40 setSocketFactory
public static void setSocketFactory(LDAPSocketFactory factory)
Establishes the default LDAPSocketFactory used when LDAPConnection
objects are constructed unless an LDAPSocketFactory is specified in
the LDAPConnection object constructor.
This method sets the default LDAPSocketFactory used for all
subsequent LDAPConnection objects constructed. If called after
LDAPConnection objects are created, those already created are not
affected even if they disconnect and establish a new connection. It
affects LDAPConnection objects only as they are constructed.
Parameters are:
factory A factory object which can construct socket
connections for an LDAPConnection.
2.6.41 startTLS
public void startTLS()
throws LDAPException
Begin using the Transport Layer Security (TLS) protocol for session
privacy [10]. If the socket factory of the connection is not capable
of initiating a TLS session, an LDAPException is thrown with the
error code TLS_NOT_SUPPORTED. If the server does not support the
transition to a TLS session, an LDAPException is thrown with the
error code returned by the server. If there are outstanding LDAP
operations on the connection, an LDAPException is thrown.
2.6.42 Constants of LDAPConnection
Expires April, 2001 [Page 54]
JAVA LDAP API April 2001
ALL_USER_ATTRS ("*") Used with search instead of an attribute
list to indicate that all attributes are to be
returned.
NO_ATTRS ("1.1") Used with search instead of an attribute list
to indicate that no attributes are to be
returned.
DEFAULT_PORT (389) Used on connect to indicate the default LDAP
port number.
SCOPE_BASE (0) Used with search to indicate that only the entry
corresponding to the base DN is to be returned.
SCOPE_ONE (1) Used with search to indicate that only immediate
subordinates of the entry corresponding to the
base DN, and not the entry corresponding to the
base DN, are to be returned.
SCOPE_SUB (2) Used with search to indicate that the entry
corresponding to the base DN as well as all
direct and indirect subordinate entries are to be
returned.
2.7 public class 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.setConstraints, or
overridden by passing an LDAPConstraints object to an operation.
2.7.1 Constructors
public LDAPConstraints()
Constructs an LDAPConstraints object that specifies the default
set of constraints.
public LDAPConstraints(int msLimit,
boolean doReferrals,
LDAPReferralHandler binder,
int hop_limit)
Constructs a new LDAPConstraints object and allows specifying
the operational constraints in that object.
Parameters are:
Expires April, 2001 [Page 55]
JAVA LDAP API April 2001
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). It is ignored for asynchronous
operations.
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. The
object may implement either the LDAPBind or the
LDAPRebind interface. It is ignored for
asynchronous operations.
hop_limit Maximum number of referrals to follow in a
sequence when attempting to resolve a request,
when doing automatic referral following. It is
ignored for asynchronous operations.
2.7.2 getClientControls
public LDAPControl[] getClientControls()
Returns controls to be used by the interface.
2.7.3 getHopLimit
public int getHopLimit()
Returns the maximum number of hops to follow during automatic
referral following.
2.7.4 getReferralFollowing
public boolean getReferralFollowing()
Specifies whether or not referrals are followed automatically.
Returns true if referrals are to be followed automatically, or false
if referrals throw an LDAPReferralException.
2.7.5 getServerControls
public LDAPControl[] getServerControls()
Expires April, 2001 [Page 56]
JAVA LDAP API April 2001
Returns controls to be sent to the server.
2.7.6 getTimeLimit
public int getTimeLimit()
Returns the maximum number of milliseconds the client waits 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.
2.7.7 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.
2.7.8 setHopLimit
public void setHopLimit(int hop_limit)
Sets the maximum number of hops to follow in sequence during
automatic referral following. The default is 10. 0 means no limit.
Parameters are:
hop_limit Maximum number of chained referrals to follow
automatically.
2.7.9 setReferralFollowing
public void setReferralFollowing(boolean doReferrals)
Specifies whether nor not referrals are followed automatically, or if
referrals throw an LDAPReferralException. Referrals of any type
other than to an LDAP server (i.e. a referral URL other than
ldap://something) are ignored on automatic referral following. The
default is false.
Expires April, 2001 [Page 57]
JAVA LDAP API April 2001
Parameters are:
doReferrals True to follow referrals automatically.
2.7.10 setReferralHandler
public void setReferralHandler (LDAPReferralHandler binder)
Specifies the object that will process authentication requests. The
default is null.
Parameters are:
binder An object that implements LDAPBind or LDAPRebind.
2.7.11 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.
2.7.12 setTimeLimit
public void setTimeLimit(int msLimit)
Sets 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.
Parameters are:
msLimit Maximum milliseconds to wait.
2.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
Expires April, 2001 [Page 58]
JAVA LDAP API April 2001
set as a Client Control, it is not sent to the server, but rather
interpreted locally by the client.
2.8.1 Constructors
public LDAPControl(String id,
boolean critical,
byte[] value)
Parameters are:
id The type of the Control, as an OID.
critical If true, the LDAP operation will fail if the
server does not support this Control.
value Control-specific data.
2.8.2 clone
public Object clone()
Returns a deep copy of the object.
2.8.3 getID
public String getID()
Returns the identifier of the control.
2.8.4 getValue
public byte[] getValue()
Returns the control-specific data of the object.
2.8.5 isCritical
public boolean isCritical()
Returns true if the control must be supported for an associated
operation to be executed.
2.8.6 register
public static void register(String oid, Class controlClass)
Expires April, 2001 [Page 59]
JAVA LDAP API April 2001
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.
2.8.7 setValue
protected void setValue(byte[] value)
Sets the control-specific data of the object. This method is for use
by extensions of LDAPControl.
Parameters are:
value The value to be assigned to the Control.
2.9 public class LDAPDITContentRuleSchema
extends LDAPSchemaElement
The LDAPDITContentRuleSchema class represents the definition of a DIT
Content Rule. It is used to discover or modify additional auxiliary
classes, mandatory and optional attributes, and restricted attributes
in effect for an object class. See [ATTR] for a description of DIT
content rule representation in LDAP.
2.9.1 Constructors
public LDAPDITContentRuleSchema(String name,
String oid,
String description,
boolean obsolete,
String[] auxiliary,
String[] required,
String[] optional,
String[] precluded,
String[] aliases)
Constructs a DIT content rule for adding to or deleting from the
schema.
public LDAPDITContentRuleSchema(String raw)
Expires April, 2001 [Page 60]
JAVA LDAP API April 2001
Constructs a DIT content rule from the raw String value returned on a
schema query for "dITContentRules".
Parameters are:
name Name of the content rule.
oid Object Identifier of the content rule - in
dotted numerical format.
description Optional description of the content rule.
obsolete true if the content rule is obsolete.
auxiliary A list of auxiliary object classes allowed for
an entry to which this content rule applies.
These may either be specified by name or
numeric oid.
required A list of user attribute types that an entry
to which this content rule applies must
contain in addition to its normal set of
mandatory attributes. These may either be
specified by name or numeric oid.
optional A list of user attribute types that an entry
to which this content rule applies may contain
in addition to its normal set of optional
attributes. These may either be specified by
name or numeric oid.
precluded A list, consisting of a subset of the optional
user attribute types of the structural and
auxiliary object classes which are precluded
from an entry to which this content rule
applies. These may either be specified by name
or numeric oid.
aliases Optional list of additional names by which the
content rule may be known; null if there are
no aliases.
raw The raw String value returned on a Directory
query for "dITContentRules".
2.9.2 getAuxiliaryClasses
public String[] getAuxiliaryClasses()
Returns the list of allowed auxiliary classes.
Expires April, 2001 [Page 61]
JAVA LDAP API April 2001
2.9.3 getOptionalAttributes
public String[] getOptionalAttributes()
Returns the list of additional optional attributes for an entry
controlled by this content rule.
2.9.4 getPrecludedAttributes
public String[]getPrecludedAttributes()
Returns the list of precluded attributes for an entry controlled by
this content rule.
2.9.5 getRequiredAttributes
public String[] getRequiredAttributes()
Returns the list of additional required attributes for an entry
controlled by this content rule.
2.10 public class LDAPDITStructureRuleSchema
extends LDAPSchemaElement
The LDAPDITStructureRuleSchema class represents the definition of a
DIT Structure Rule. It is used to discover or modify which object
classes a particular object class may be subordinate to in the DIT.
See [ATTR] for a description of DIT structure rule representation in
LDAP.
2.10.1 Constructors
public LDAPDITStructureRuleSchema(String name,
int ruleID,
String description,
boolean obsolete,
String nameForm,
String[] superiorIDs,
String[] aliases)
Constructs a DIT structure rule for adding to or deleting from the
schema.
public LDAPDITStructureRuleSchema(String raw)
Constructs a DIT structure rule from the raw String value returned on
a schema query for "dITStructureRules".
Expires April, 2001 [Page 62]
JAVA LDAP API April 2001
Parameters are:
name Name of the structure rule.
ruleID Unique identifier of the structure rule. NOTE:
this is an integer, not a dotted numerical
identifier. Structure rules aren't identified
by OID.
description Optional description of the structure rule.
obsolete true if the structure rule is obsolete.
nameForm Either the identifier or name of a name form.
This is used to indirectly refer to the object
class that this structure rule applies to.
superiorIDs List of superior structure rules - specified
by their integer ID. The object class
specified by this structure rule (via the
nameForm parameter) may only be subordinate in
the DIT to object classes of those represented
by the structure rules here; MAY be null.
aliases Optional list of additional names by which the
structure rule may be known; null if there are
no aliases.
raw The raw String value returned on a Directory
query for "dITStructureRules".
2.10.2 getNameForm
public String getNameForm()
Returns the NameForm that this structure rule controls. You can get
the actual object class that this structure rule controls by calling
getNameForm().getObjectClass().
2.10.3 getRuleID
public int getRuleID()
Returns the rule ID for this structure rule. Note that this returns
an integer rather than a dotted decimal OID. Objects of this class do
not have an OID, thus getID will return null.
2.10.4 getSuperiors
public String[] getSuperiors()
Expires April, 2001 [Page 63]
JAVA LDAP API April 2001
Returns a list of all structure rules that are superior to this
structure rule. To resolve to an object class, you need to first
resolve the superior id to another structure rule, then call
getNameForm().getObjectClass() on that structure rule.
2.11 public class LDAPDN
A utility class representing a distinguished name (DN).
2.11.1 equals
public static boolean equals(String dn1, String dn2)
Compares the two strings per the distinguishedNameMatch matching rule
[ATTR]. An API implementation MUST use caseIgnoreMatch equality
matching for the attributes listed in section 2 of [ATTR].
IllegalArgumentException is thrown if one or both DNs are invalid.
UnsupportedOperationException is thrown if the API implementation is
not able to determine if the DNs match or not.
Parameters are:
dn1 String form of first DN to compare.
dn2 String form of second DN to compare.
2.11.2 escapeRDN
public static String escapeRDN(String rdn)
Returns the RDN after escaping the characters requiring escaping [4].
For example, for the rdn "cn=Example, Inc", "cn=Example\, Inc" is
returned.
Parameters are:
rdn The RDN to escape.
2.11.3 explodeDN
public static String[] explodeDN(String dn,
boolean noTypes)
Returns the individual components of a distinguished name (DN).
Parameters are:
Expires April, 2001 [Page 64]
JAVA LDAP API April 2001
dn Distinguished name, e.g. "cn=Babs
Jensen,ou=Accounting,dc=example,dc=com"
noTypes If true, returns only the values of the
components, and not the names, e.g. "Babs
Jensen", "Accounting", "Example", "com" - instead
of "cn=Babs Jensen","ou=Accounting","dc=Example",
and "dc=com".
2.11.4 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.
2.11.5 isValid
public static boolean isValid(String dn)
Returns true if the string conforms to distinguished name syntax.
Parameters are:
dn String to evaluate for distinguished name syntax.
2.11.6 normalize
public static String normalize(String dn)
Returns the DN normalized by removal of non-significant space
characters as per RFC 2253, section 4 [DN].
Parameters are:
dn The DN to normalize.
2.11.7 unescapeRDN
public static String unescapeRDN(String rdn)
Expires April, 2001 [Page 65]
JAVA LDAP API April 2001
Returns the RDN after unescaping the characters requiring escaping
[DN]. For example, for the rdn "cn=Example\, Inc", "cn=Example, Inc"
is returned. IllegalArgumentException is thrown if the RDN cannot be
parsed.
Parameters are:
rdn The RDN to unescape.
2.12 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 either enumerating an
LDAPSearchResults, or calling LDAPSearchResult.getEntry.
2.12.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.
2.12.2 getAttribute
public LDAPAttribute getAttribute(String attrName)
Expires April, 2001 [Page 66]
JAVA LDAP API April 2001
Returns the attribute matching the specified attrName.
Parameters are:
attrName The name of the attribute. See 2.3.5 for the
syntax and semantics relevant to this parameter.
2.12.3 getAttributeSet
public LDAPAttributeSet getAttributeSet()
Returns the attribute set of the entry. All base and subtype variants
of all attributes are returned. The LDAPAttributeSet returned MAY be
empty if there are no attributes in the entry.
public LDAPAttributeSet getAttributeSet(String subtype)
Returns an attribute set from the entry, consisting of only those
attributes matching the specified subtype(s). This may be used to
extract only a particular language variant subtype of each attribute,
if it exists. "subtype" may be, for example, "lang-ja", "binary", or
"lang-ja;phonetic". If more than one subtype is specified, separated
with a semicolon, only those attributes with all of the named
subtypes will be returned. The LDAPAttributeSet returned may be
empty if there are no matching attributes in the entry.
Parameters are:
subtype One or more subtype specification(s), separated
with semicolons. "lang-ja" and
"lang-en;phonetic" are valid subtype
specifications.
2.12.4 getDN
public String getDN()
Returns the distinguished name of the entry.
2.13 public interface LDAPEntryComparator
An object of this class can implement arbitrary sorting algorithms
for search results.
2.13.1 isGreater
Expires April, 2001 [Page 67]
JAVA LDAP API April 2001
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.
2.14 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 an entry already exists with the DN of the entry to be
added).
Most errors that occur throw this type of exception. The
getLDAPResultCode() method returns the specific result code.
2.14.1 Constructors
public LDAPException()
Constructs a default exception with no specific error information.
public LDAPException(String message,
int resultCode)
Constructs an exception with a result code and a specified string as
additional information.
public LDAPException(String message,
int resultCode,
Throwable rootException)
Constructs an exception with a result code, a specified string, and
an embedded root exception as additional information.
public LDAPException(String message,
int resultCode,
String matchedDN)
Constructs an exception with a result code, a specified string as
additional information, and the maximal subset of a specified DN
which could be matched by the server on a search operation.
Expires April, 2001 [Page 68]
JAVA LDAP API April 2001
Parameters are:
message The additional error information
resultCode The result code returned
matchedDN The DN of the most immediate ancestor of a
specified search DN which could be found by the
server on a search operation
rootException An exception which caused the failure, if any
2.14.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 known to the API.
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 "Result codes"
below.
locale A Locale in which to render the error String.
Expires April, 2001 [Page 69]
JAVA LDAP API April 2001
2.14.3 getCause
public Throwable getCause()
Returns the lower level Exception which caused the failure, if any.
For example, an IOException with additional information MAY be
returned on a CONNECT_ERROR failure.
2.14.4 getLDAPErrorMessage
public String getLDAPErrorMessage()
Returns the error message, if this message is available (that is, if
this message was set). If the message was not set, this method
returns null.
2.14.5 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 [LDAPv3]. Otherwise, a local
error code is returned (see "Result codes" below).
2.14.6 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
2.14.7 Result codes
See [LDAPv3] for a discussion of the meanings and values of the
codes. The corresponding ASN.1 name from [LDAPv3] is provided in
parentheses.
Expires April, 2001 [Page 70]
JAVA LDAP API April 2001
ADMIN_LIMIT_EXCEEDED (adminLimitExceeded)
AFFECTS_MULTIPLE_DSAS (affectsMultipleDSAs)
ALIAS_DEREFERENCING_PROBLEM (aliasDereferencingProblem)
ALIAS_PROBLEM (aliasProblem)
ATTRIBUTE_OR_VALUE_EXISTS (attributeOrValueExists)
AUTH_METHOD_NOT_SUPPORTED (authMethodNotSupported)
BUSY (busy)
COMPARE_FALSE (compareFalse)
COMPARE_TRUE (compareTrue)
CONFIDENTIALITY_REQUIRED (confidentialityRequired)
CONSTRAINT_VIOLATION (constraintViolation)
ENTRY_ALREADY_EXISTS (entryAlreadyExists)
INAPPROPRIATE_AUTHENTICATION (inappropriateAuthentication)
INAPPROPRIATE_MATCHING (inappropriateMatching)
INSUFFICIENT_ACCESS_RIGHTS (insufficientAccessRights)
INVALID_ATTRIBUTE_SYNTAX (invalidAttributeSyntax)
INVALID_CREDENTIALS (invalidCredentials)
INVALID_DN_SYNTAX (invalidDNSyntax)
IS_LEAF (isLeaf)
LOOP_DETECT (loopDetect)
NAMING_VIOLATION (namingViolation)
NO_SUCH_ATTRIBUTE (noSuchAttribute)
NO_SUCH_OBJECT (noSuchObject)
NOT_ALLOWED_ON_NONLEAF (notAllowedOnNonLeaf)
NOT_ALLOWED_ON_RDN (notAllowedOnRDN)
OBJECT_CLASS_MODS_PROHIBITED (objectClassModsProhibited)
OBJECT_CLASS_VIOLATION (objectClassViolation)
OPERATIONS_ERROR (operationsError)
OTHER (other)
PROTOCOL_ERROR (protocolError)
REFERRAL (referral)
SASL_BIND_IN_PROGRESS (saslBindInProgress)
SIZE_LIMIT_EXCEEDED (sizeLimitExceeded)
STRONG_AUTH_REQUIRED (strongAuthRequired)
SUCCESS (success)
TIME_LIMIT_EXCEEDED (timeLimitExceeded)
UNAVAILABLE (unavailable)
UNAVAILABLE_CRITICAL_EXTENSION (unavailableCriticalExtension)
UNDEFINED_ATTRIBUTE_TYPE (undefinedAttributeType)
UNWILLING_TO_PERFORM (unwillingToPerform)
Local errors, resulting from actions other than an operation on a
server, are among the following:
AMBIGUOUS_RESPONSE (0x65)
AUTH_UNKNOWN (0x56)
CLIENT_LOOP (0x60)
CONNECT_ERROR (0x5b)
CONTROL_NOT_FOUND (0x5d)
DECODING_ERROR (0x54)
ENCODING_ERROR (0x53)
FILTER_ERROR (0x57)
Expires April, 2001 [Page 71]
JAVA LDAP API April 2001
INVALID_RESPONSE (0x64)
LOCAL_ERROR (0x52)
LDAP_NOT_SUPPORTED (0x5c)
LDAP_TIMEOUT (0x55)
MORE_RESULTS_TO_RETURN (0x5f)
NO_MEMORY (0x5a)
NO_RESULTS_RETURNED (0x5e)
REFERRAL_LIMIT_EXCEEDED (0x61)
SERVER_DOWN (0x51)
USER_CANCELLED (0x58)
TLS_NOT_SUPPORTED (0x70)
2.15 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.
2.15.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.
2.15.2 getID
public String getID()
Returns the unique identifier of the operation.
2.15.3 getValue
public byte[] getValue()
Returns the operation-specific data (not a copy, a reference).
2.15.4 setValue
protected void setValue(byte[] value)
Expires April, 2001 [Page 72]
JAVA LDAP API April 2001
Sets the operation-specific data of the object. This method is for
use by extensions of LDAPExtendedOperation.
Parameters are:
value The value to be assigned to the object.
2.16 public class LDAPExtendedResponse
extends LDAPResponse
An LDAPExtendedResponse object encapsulates a server response to an
asynchronous extended operation request.
2.16.1 getID
public String getID()
Returns the OID of the response.
2.16.2 getValue
public byte[] getValue()
Returns the raw bytes of the value part of the response.
2.17 public interface LDAPListener
Represents the message queue associated with a particular
asynchronous LDAP operation or operations.
2.17.1 getMessageIDs
public int[] getMessageIDs()
Returns the message IDs for all outstanding requests, i.e. requests
for which a response has not been received from the server or which
still have messages to be retrieved with getResponse. The last ID in
the array is the messageID of the latest submitted request.
2.17.2 getResponse
public LDAPMessage getResponse()throws LDAPException
Blocks until a response is available, or until all operations
associated with the object have completed or been canceled, and
returns the response.
Expires April, 2001 [Page 73]
JAVA LDAP API April 2001
public LDAPMessage getResponse(int msgid)throws LDAPException
Blocks until a response is available for a particular message ID, or
until all operations associated with the message ID have completed or
been canceled, and returns the response.
Parameters are:
msgid A particular message to query for responses
available.
2.17.3 isResponseReceived
public boolean isResponseReceived()
Reports true if any response has been received from the server and
not yet retrieved with getResponse. If getResponse has been used to
retrieve all messages received to this point, then isResponseReceived
returns false.
public boolean isResponseReceived(int msgid)
Reports true if a response has been received from the server for a
particular message ID but not retrieved with getResponse.
Parameters are:
msgid A particular message to query for responses
available.
2.17.4 merge
public void merge(LDAPListener listener2)
Merges two listeners. Moves/appends the content from another
listener to this one.
2.18 public class LDAPMatchingRuleSchema
extends LDAPSchemaElement
The LDAPMatchingRuleSchema class represents the definition of a
matching rule. It is used to query matching rule syntax, and to add
or delete a matching rule definition in a Directory. See [ATTR] for a
description of matching rule representation in LDAP.
Expires April, 2001 [Page 74]
JAVA LDAP API April 2001
2.18.1 Constructors
public LDAPMatchingRuleSchema(String name,
String oid,
String description,
String[] attributes,
String syntaxString,
String[] aliases)
public LDAPMatchingRuleSchema(String name,
String oid,
String description,
boolean obsolete,
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 Object Identifier of the attribute - in dotted
numerical format.
description Optional description of the attribute.
attributes OIDs of attributes to which the rule applies.
The parameter MAY be null.
obsolete true if this matching rule is obsolete.
syntaxString Object Identifier of the syntax that this
matching rule is valid for - 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".
Expires April, 2001 [Page 75]
JAVA LDAP API April 2001
rawMatchingRuleUse The raw String value returned on a Directory
query for "matchingRuleUse". The parameter MAY
be null.
2.18.2 getAttributes
public String[] getAttributes()
Returns the OIDs of the attributes to which this rule applies.
2.18.3 getSyntaxString
public String[] getSyntaxString()
Returns the OID of the syntax that this matching rule is valid for.
2.19 public class LDAPMatchingRuleUseSchema
extends LDAPSchemaElement
The LDAPMatchingRuleUseSchema class represents the definition of a
matching rule use. It is used to discover or modify which attributes
are suitable for use with an extensible matching rule. It contains
the name and identifier of a matching rule, and a list off attributes
that it applies to. See [ATTR] for a description of matching rule
use representation in LDAP.
2.19.1 Constructors
public LDAPMatchingRuleUseSchema(String name,
String oid,
String description,
boolean obsolete,
String[] attributes,
String[] aliases)
Constructs a matching rule use definition for adding to or deleting
from the schema.
public LDAPMatchingRuleUseSchema(String raw)
Constructs a matching rule use definition from the raw String value
returned on a schema query for "matchingRuleUse".
Parameters are:
name Name of the matching rule.
Expires April, 2001 [Page 76]
JAVA LDAP API April 2001
oid Object Identifier of the matching rule - in
dotted numerical format.
description Optional description of the matching rule use.
obsolete true if the matching rule use is obsolete.
attributes List of attributes that this matching rule
applies to. These values may be either the
names or numeric oids of the attributes
aliases Optional list of additional names by which the
matching rule use may be known; null if there
are no aliases.
raw The raw String value returned on a Directory
query for "matchingRuleUse".
2.19.2 getAttributes
public String[] getAttributes()
Returns an array of all the attributes that this matching rule
applies to.
2.20 public class LDAPMessage
Base class for asynchronous LDAP request and response messages.
2.20.1 getControls
public LDAPControl[] getControls()
Returns any controls in the message.
2.20.2 getMessageID
public int getMessageID()
Returns the message ID.
2.20.3 getType
public int getType()
Returns the LDAP operation type of the message. The type is one of
the following:
Expires April, 2001 [Page 77]
JAVA LDAP API April 2001
BIND_REQUEST (0x0)
BIND_RESPONSE (0x1)
UNBIND_REQUEST (0x2)
SEARCH_REQUEST (0x3)
SEARCH_RESPONSE (0x4)
SEARCH_RESULT (0x5)
MODIFY_REQUEST (0x6)
MODIFY_RESPONSE (0x7)
ADD_REQUEST (0x8)
ADD_RESPONSE (0x9)
DEL_REQUEST (0xa)
DEL_RESPONSE (0xb)
MODIFY_RDN_REQUEST (0xc)
MODIFY_RDN_RESPONSE (0xd)
COMPARE_REQUEST (0xe)
COMPARE_RESPONSE (0xf)
ABANDON_REQUEST (0x10)
SEARCH_RESULT_REFERENCE (0x13)
EXTENDED_REQUEST (0x17)
EXTENDED_RESPONSE (0x18)
2.21 public class LDAPModification
A single change specification for an LDAPAttribute.
2.21.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:
ADD The value should be added to
the attribute
DELETE The value should be removed
from the attribute
REPLACE The value should replace all
existing values of the
attribute
attr The attribute (possibly with values) to be
modified.
Expires April, 2001 [Page 78]
JAVA LDAP API April 2001
2.21.2 getAttribute
public LDAPAttribute getAttribute()
Returns the attribute (possibly with values) to be modified.
2.21.3 getOp
public int getOp()
Returns the type of modification specified by this object.
2.21.4 Constants of LDAPModification
ADD (0) The value should be added to the attribute
DELETE (1) The value should be removed from the attribute
REPLACE (2) The value should replace all existing values of
the attribute
2.22 public class LDAPModificationSet
A collection of modifications to be made to the attributes of a
single entry.
2.22.1 Constructors
public LDAPModificationSet()
Constructs a new, empty set of modifications.
2.22.2 add
public 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.
Expires April, 2001 [Page 79]
JAVA LDAP API April 2001
attr The attribute (possibly with values) to be
modified.
2.22.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.
2.22.4 remove
public 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.
2.22.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.
2.22.6 size
public int size()
Retrieves the number of LDAPModification objects in this set.
2.23 public class LDAPNameFormSchema
extends LDAPSchemaElement
Expires April, 2001 [Page 80]
JAVA LDAP API April 2001
The LDAPNameFormSchema class represents the definition of a Name
Form. It is used to discover or modify the allowed naming attributes
for a particular object class. See [ATTR] for a description of name
form representation in LDAP.
2.23.1 Constructors
public LDAPNameFormSchema(String name,
String oid,
String description,
boolean obsolete,
String objectClass,
String[] required,
String[] optional,
String[] aliases)
Constructs a name form for adding to or deleting from the schema.
public LDAPNameFormSchema(String raw)
Constructs a DIT content rule from the raw String value returned on a
schema query for "nameForms".
Parameters are:
name Name of the name form.
oid Object Identifier of the name form - in dotted
numerical format.
description Optional description of the name form.
obsolete true if the name form is obsolete.
objectClass The object to which this name form applies.
This may either be specified by name or
numeric oid.
required A list of the attributes that must be present
in the RDN of an entry that this name form
controls. These may either be specified by
name or numeric oid.
optional A list of the attributes that may be present
in the RDN of an entry that this name form
controls. These may either be specified by
name or numeric oid.
aliases Optional list of additional names by which the
name form may be known; null if there are no
aliases.
Expires April, 2001 [Page 81]
JAVA LDAP API April 2001
raw The raw String value returned on a Directory
query for "nameForms".
2.23.2 getObjectClass
public String getObjectClass()
Returns the name of the object class that this name form applies to.
2.23.3 getOptionalNamingAttributes
public String[]getOptionalNamingAttributes()
Returns the list of optional naming attributes for an entry
controlled by this content rule.
2.23.4 getRequiredNamingAttributes
public String[]getRequiredNamingAttributes()
Returns the list of required naming attributes for an entry
controlled by this name form.
2.24 public class LDAPObjectClassSchema
extends LDAPSchemaElement
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
[ATTR] for a description of object class representation in LDAP.
2.24.1 Constructors
public LDAPObjectClassSchema(String name,
String oid,
String[] superiors,
String description,
String[] required,
String[] optional,
int type,
String[] aliases,
boolean obsolete)
Constructs an object class definition for adding to or deleting from
a Directory.
Expires April, 2001 [Page 82]
JAVA LDAP API April 2001
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 Object Identifier 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.
obsolete true if this object class is obsolete.
raw The raw String value returned on a Directory
query for "objectclasses".
2.24.2 getOptionalAttributes
public String[] getOptionalAttributes()
Returns a list of attributes acceptable but not required of an entry
with this object class.
2.24.3 getRequiredAttributes
public String[] getRequiredAttributes()
Returns a list of attributes required of an entry with this object
class.
Expires April, 2001 [Page 83]
JAVA LDAP API April 2001
2.24.4 getSuperiors
public String[] getSuperiors()
Returns the object classes which this one derives from.
2.24.5 getType
public int getType()
Returns one of ABSTRACT, AUXILIARY, or STRUCTURAL. These are
constants defined in LDAPObjectClassSchema.
2.25 public interface LDAPRebind
extends LDAPReferralHandler
Used to provide credentials for reauthentication on processing a
referral.
2.25.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 host identifier representing the IP
address of a host running an LDAP server. See
2.6.8 for a discussion of valid identifiers.
port Contains the TCP port number to connect to.
2.26 public class LDAPRebindAuth
Represents information used to authenticate the client in cases where
the client follows referrals automatically.
2.26.1 Constructors
public LDAPRebindAuth( String dn,
String password )
Constructs information that is used by the client for authentication
when following referrals automatically.
Expires April, 2001 [Page 84]
JAVA LDAP API April 2001
public LDAPRebindAuth( String dn,
byte[] password )
Constructs information that is used by the client for authentication
when following referrals automatically.
Parameters are:
dn Distinguished name to use in authenticating to
the server.
password Password to use in authenticating to the server.
2.26.2 getDN
public String getDN()
Returns the distinguished name to be used for reauthentication on
automatic referral following.
2.26.3 getPassword
public byte[] getPassword()
Returns the password to be used for reauthentication on automatic
referral following.
2.27 public class LDAPReferralException
extends LDAPException
This exception, derived from LDAPException, is thrown when a server
returns a referral on a synchronous request and automatic referral
following has not been enabled.
2.27.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.
Expires April, 2001 [Page 85]
JAVA LDAP API April 2001
public LDAPReferralException(String message,
Throwable rootException)
Constructs a default exception with a specified string as additional
information and an exception that indicates a failure to follow a
referral. This exception applies only to synchronous operations and
is thrown only on receipt of a referral when the referral was not
followed.
public LDAPReferralException(String message,
int resultCode,
String serverMessage)
public LDAPReferralException(String message,
int resultCode,
String serverMessage,
Throwable rootException)
Parameters are:
message The additional error information.
resultCode The result code returned
serverMessage Error message specifying additional information
from the server.
rootException An exception which caused referral following to
fail
2.27.2 getFailedReferral
public String getFailedReferral()
Gets the referral that could not be processed. If multiple referrals
could not be processed, the method returns one of them.
2.27.3 getReferrals
public String[] getReferrals()
Gets the list of referrals (LDAP URLs to other servers) returned by
the LDAP server. If the scope field of a referral of type
SearchResultReference must be modified in order to follow the
referral, the API implementation MUST modify the scope field of the
URL before returning the URL to the application.
The referrals MAY include URLs of a type other than ones for an LDAP
Expires April, 2001 [Page 86]
JAVA LDAP API April 2001
server (i.e. a referral URL other than ldap://something).
2.27.4 setFailedReferral
public void setFailedReferral(String url)
Sets a referral that could not be processed.
2.28 public interface LDAPReferralHandler
Shared ancestor to the two types of referal objects - LDAPBind and
LDAPRebind.
2.29 public class LDAPResponse
extends LDAPMessage
Represents the response to a particular asynchronous LDAP operation.
2.29.1 getErrorMessage
public String getErrorMessage()
Returns any error message in the response.
2.29.2 getMatchedDN
public String getMatchedDN()
Returns the partially matched DN field, if any, in a server response.
2.29.3 getReferrals
public String[] getReferrals()
Returns all referrals, if any, in a server response.
2.29.4 getResultCode
public int getResultCode()
Returns the result code in a server response, as defined in [5].
2.30 public class LDAPResponseListener
implements LDAPListener
Expires April, 2001 [Page 87]
JAVA LDAP API April 2001
Represents the message queue associated with a particular
asynchronous LDAP operation or operations.
2.30.1 getMessageIDs
public int[] getMessageIDs()
Returns the message IDs for all outstanding requests, i.e. requests
for which a response has not been received from the server or which
still have messages to be retrieved with getResponse. The last ID in
the array is the messageID of the latest submitted request.
2.30.2 getResponse
public LDAPMessage getResponse()throws LDAPException
Blocks until a response is available, or until all operations
associated with the object have completed or been canceled, and
returns the response.
public LDAPMessage getResponse(int msgid)throws LDAPException
Blocks until a response is available for a particular message ID, or
until all operations associated with the message ID have completed or
been canceled, and returns the response.
Parameters are:
msgid A particular message to query for responses
available.
2.30.3 isResponseReceived
public boolean isResponseReceived()
Reports true if any response has been received from the server and
not yet retrieved with getResponse. If getResponse has been used to
retrieve all messages received to this point, then isResponseReceived
returns false.
public boolean isResponseReceived(int msgid)
Reports true if a response has been received from the server for a
particular message ID.
Parameters are:
Expires April, 2001 [Page 88]
JAVA LDAP API April 2001
msgid A particular message to query for responses
available.
2.30.4 merge
public void merge(LDAPListener listener2)
Merges two response listeners. Moves/appends the content from another
listener to this one.
2.31 public class LDAPSchema
The LDAPSchema supports querying a Directory Server for its schema,
and obtaining definitions of individual schema elements.
2.31.1 Constructors
public LDAPSchema()
Constructs an empty LDAPSchema object.
2.31.2 fetchSchema
public void fetchSchema(LDAPConnection ld) throws LDAPException
Retrieves the entire schema from a Directory Server.
public void fetchSchema(LDAPConnection ld,
String dn) throws LDAPException
Retrieves the schema controlling a particular entry in the Directory
Server.
The fetchSchema methods are the only methods that interact with a
Directory Server. The other methods access information acquired
through fetchSchema. An LDAPException is thrown as for
LDAPConnection.search() (2.6.34) if the schema cannot be retrieved
with the specified connection, or if the subschemaSubentry attribute
used to locate the schema contains multiple values.
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.
Expires April, 2001 [Page 89]
JAVA LDAP API April 2001
2.31.3 getAttribute
public LDAPAttributeSchema getAttribute( String name )
Returns a particular attribute definition, or null if not found.
Parameters are:
name Name of the attribute for which a definition is
to be returned.
2.31.4 getAttributeNames
public Enumeration getAttributeNames()
Returns an enumeration of attribute names.
2.31.5 getAttributes
public Enumeration getAttributes()
Returns an enumeration of attribute definitions.
2.31.6 getDITContentRule
public LDAPDITContentRuleSchema getDITContentRule( String name )
Returns a particular content rule definition, or null if not found.
Parameters are:
name Name of the content rule for which a definition
is to be returned.
2.31.7 getDITContentRuleNames
public Enumeration getDITContentRuleNames ()
Returns an enumeration of content rule names.
2.31.8 getDITContentRules
public Enumeration getDITContentRules()
Returns an enumeration of LDAPDITContentRuleSchema objects.
Expires April, 2001 [Page 90]
JAVA LDAP API April 2001
2.31.9 getDITStructureRule
public LDAPDITStructureRuleSchema getDITStructureRule( String name )
public LDAPDITStructureRuleSchema getDITStructureRule( int ID )
Returns a particular structure rule definition, or null if not found.
Parameters are:
name Name of the structure rule for which a definition
is to be returned.
ID Identifier of the structure rule for which a
definition is to be returned.
2.31.10 getDITStructureRuleNames
public Enumeration getDITStructureRuleNames ()
Returns an enumeration of structure rule names.
2.31.11 getDITStructureRules
public Enumeration getDITStructureRules()
Returns an enumeration of LDAPDITStructureRuleSchema objects.
2.31.12 getMatchingRule
public LDAPMatchingRuleSchema getMatchingRule( String name )
Returns a particular matching rule definition, or null if not found.
Parameters are:
name Name of the matching rule for which a definition
is to be returned.
2.31.13 getMatchingRuleNames
public Enumeration getMatchingRuleNames()
Returns an enumeration of matching rule names.
Expires April, 2001 [Page 91]
JAVA LDAP API April 2001
2.31.14 getMatchingRules
public Enumeration getMatchingRules()
Returns an enumeration of matching rule definitions.
2.31.15 getMatchingRuleUse
public LDAPMatchingRuleUseSchema getMatchingRuleUse( String name )
Returns a particular matching rule use definition, or null if not
found.
Parameters are:
name Name of the matching rule use for which a
definition is to be returned.
2.31.16 getMatchingRuleUseNames
public Enumeration getMatchingRuleUseNames()
Returns an enumeration of matching rule use names.
2.31.17 getMatchingRuleUses
public Enumeration getMatchingRuleUses()
Returns an enumeration of LDAPMatchingRuleUseSchema objects.
2.31.18 getNameForm
public LDAPNameFormSchema getNameForm( String name )
Returns a particular name form definition, or null if not found.
Parameters are:
name Name of the name form for which a definition is
to be returned.
2.31.19 getNameFormNames
public Enumeration getNameFormNames ()
Returns an enumeration of name form names.
Expires April, 2001 [Page 92]
JAVA LDAP API April 2001
2.31.20 getNameForms
public Enumeration getNameForms()
Returns an enumeration of LDAPNameFormSchema objects.
2.31.21 getObjectClass
public LDAPObjectClassSchema getObjectClass( String name )
Returns a particular object class definition, or null if not found.
Parameters are:
name Name of the object class for which a definition
is to be returned.
2.31.22 getObjectClasses
public Enumeration getObjectClasses()
Returns an enumeration of object class definitions.
2.31.23 getObjectClassNames
public Enumeration getObjectClassNames()
Returns an enumeration of object class names.
2.31.24 getSyntax
public LDAPSyntaxSchema getSyntax( String oid )
Returns a particular syntax definition, or null if not found.
Parameters are:
oid Identifier of the syntax for which a definition
is to be returned.
2.31.25 getSyntaxes
public Enumeration getSyntaxes()
Returns an enumeration of LDAPSyntaxSchema objects.
Expires April, 2001 [Page 93]
JAVA LDAP API April 2001
2.32 public abstract class LDAPSchemaElement
The LDAPSchemaElement class is the base class for representing schema
elements in LDAP.
2.32.1 add
public void add(LDAPConnection ld) throws LDAPException
public void add(LDAPConnection ld, String dn) throws LDAPException
Adds the definition to a Directory. An exception is thrown if the
definition can't be added.
Parameters are:
ld An open connection to a Directory Server.
Typically the connection must have been
authenticated to add a schema definition.
dn Entry at which to determine the subschemasubentry
to which the schema element is to be added.
2.32.2 getAliases
public String[] getAliases()
Returns an array of alternative names of the element, or null if
there are none. With respect to the protocol-level schema element
syntax definition of [ATTR], the array consists of all values but the
first of the NAME qualifier.
2.32.3 getDescription
public String getDescription()
Returns the description of the element. With respect to the protocol-
level schema element syntax definition of [ATTR], the value is that
of the DESC qualifier.
2.32.4 getName
public String getName()
Returns the name of the element. With respect to the protocol-level
schema element syntax definition of [ATTR], the value is that of the
first NAME qualifier.
Expires April, 2001 [Page 94]
JAVA LDAP API April 2001
2.32.5 getID
public String getID()
Returns the Object Identifier of the element.
2.32.6 getQualifier
public String[] getQualifier(String name)
Returns an array of all values of a specified optional or
experimental qualifier of the element. This method may be used to
access the values of vendor-specific qualifiers (which begin with "X-
" [ATTR]).
Parameters are:
name The name of the qualifier, case-sensitive.
2.32.7 getQualifierNames
public Enumeration getQualifierNames()
Returns an enumeration of all qualifiers of the element which are not
defined in [ATTR].
2.32.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.
2.32.9 isObsolete
public boolean isObsolete()
Returns true if the element has the OBSOLETE qualifier in its LDAP
definition [ATTR].
2.32.10 modify
public void modify(LDAPConnection ld
LDAPSchemaElement newValue) throws LDAPException
Expires April, 2001 [Page 95]
JAVA LDAP API April 2001
public void modify(LDAPConnection ld
LDAPSchemaElement newValue,
String dn) throws LDAPException
Replace a single value of the schema element definition in the
schema. An exception is thrown if the definition can't be modified.
Parameters are:
ld An open connection to a Directory Server.
Typically the connection must have been
authenticated to modify a schema definition.
newValue The new schema element value.
dn Entry at which to determine the subschemasubentry
to store the schema change in.
2.32.11 remove
public void remove(LDAPConnection ld) throws LDAPException
public void remove(LDAPConnection ld, String dn) throws LDAPException
Removes the definition from a Directory. An exception is thrown if
the definition can't be removed.
Parameters are:
ld An open connection to a Directory Server.
Typically the connection must have been
authenticated to remove a schema definition.
dn Entry at which to determine the subschemasubentry
to remove the schema element from.
2.32.12 setQualifier
public void setQualifier(String name, String[] values)
Sets the values of a specified optional or experimental qualifier of
the element. This method may be used to set the values of vendor-
specific qualifiers (which begin with "X-" [ATTR]).
Parameters are:
name The name of the qualifier, case-sensitive.
values The values to set for the qualifier.
Expires April, 2001 [Page 96]
JAVA LDAP API April 2001
2.33 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.setSearchConstraints, or
overridden by passing an LDAPConstraints object to the search
operation.
2.33.1 Constructors
public LDAPSearchConstraints()
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,
LDAPReferralHandler binder,
int hop_limit)
Constructs a new LDAPSearchConstraints object and allows specifying
the operational constraints in that object.
Parameters are:
msLimit Maximum time in milliseconds to wait for results
(0 by default, which means that there is no
maximum time limit). This is an interface-imposed
limit.
serverTimeLimit Maximum time in seconds that the server should
spend returning results. This is a server-imposed
limit. The default of 0 means no time limit.
dereference Specifies when aliases should be dereferenced.
MUST be either DEREF_NEVER, DEREF_FINDING,
DEREF_SEARCHING, or DEREF_ALWAYS (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
Expires April, 2001 [Page 97]
JAVA LDAP API April 2001
if the server sends back a referral (false by
default). It is ignored for asynchronous
operations.
batchSize Specify the number of results to block on during
enumeration. 0 means to block until all results
are in (1 by default). It is ignored for
asynchronous operations.
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. The
object implements either the LDAPBind or the
LDAPRebind interface. It is ignored for
asynchronous operations.
hop_limit Maximum number of referrals to follow in a
sequence when attempting to resolve a request,
when doing automatic referral following. It is
ignored for asynchronous operations. The value is
10 by default.
2.33.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.
2.33.3 getDereference
public int getDereference()
Specifies when aliases should be dereferenced. Returns either
DEREF_NEVER, DEREF_FINDING, DEREF_SEARCHING, or
DEREF_ALWAYS.
2.33.4 getMaxResults
public int getMaxResults()
Returns the maximum number of search results to be returned; 0 means
no limit.
2.33.5 getServerTimeLimit
Expires April, 2001 [Page 98]
JAVA LDAP API April 2001
public int getServerTimeLimit()
Reports the maximum number of seconds that the server is to wait when
returning search results while using this constraint object
2.33.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.
2.33.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 DEREF_NEVER, DEREF_FINDING,
DEREF_SEARCHING, or DEREF_ALWAYS.
2.33.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 Maximum number of search results to return.
2.33.9 setServerTimeLimit
public void setServerTimeLimit(int seconds)
Sets the maximum number of seconds that the server is to wait when
returning search results. The parameter is only recognized on search
operations.
Expires April, 2001 [Page 99]
JAVA LDAP API April 2001
2.33.10 Constants of LDAPSearchConstraints
DEREF_NEVER (0) Aliases are never dereferenced.
DEREF_SEARCHING (1) Aliases are dereferenced when searching the
entries beneath the starting point of the search
(but not when finding the starting entry).
DEREF_FINDING (2) Aliases are dereferenced when finding the
starting point for the search (but not when
searching under that starting entry).
DEREF_ALWAYS (3) Aliases are always dereferenced (both when
finding the starting point for the search and
when searching under that starting entry).
2.34 public class LDAPSearchListener
implements LDAPListener
An LDAPSearchListener manages search results and references returned
on one or more asynchronous search requests.
2.34.1 getMessageIDs
public int[] getMessageIDs()
Returns the message IDs for all outstanding requests, i.e. requests
for which a response has not been received from the server or which
still have messages to be retrieved with getResponse. The last ID in
the array is the messageID of the latest submitted request.
2.34.2 getResponse
public LDAPMessage getResponse() throws LDAPException
Blocks until a response is available, or until all operations
associated with the object have completed or been canceled, and
returns the response.
public LDAPMessage getResponse(int msgid) throws LDAPException
Blocks until a response is available for a particular message ID, or
until all operations associated with the message ID have completed or
been canceled, and returns the response.
Parameters are:
Expires April, 2001 [Page 100]
JAVA LDAP API April 2001
msgid A particular message to query for responses
available.
2.34.3 isComplete
public boolean isComplete(int msgid)
Reports true if all results have been received for a particular
message ID, i.e. a response has been received from the server for the
id. There may still be messages waiting to be retrieved with
getResponse.
Parameters are:
msgid A particular message to query for completion.
2.34.4 isResponseReceived
public boolean isResponseReceived()
Reports true if any response has been received from the server and
not yet retrieved with getResponse. If getResponse has been used to
retrieve all messages received to this point, then isResponseReceived
returns false.
public boolean isResponseReceived(int msgid)
Reports true if a response has been received from the server for a
particular message ID.
Parameters are:
msgid A particular message to query for responses
available.
2.34.5 merge
public void merge(LDAPSearchListener listener2)
Merges two search listeners. Moves/appends the content from another
search listener to this one.
2.35 public class LDAPSearchResult
extends LDAPMessage
Expires April, 2001 [Page 101]
JAVA LDAP API April 2001
An LDAPSearchResult object encapsulates a single asynchronous search
result.
2.35.1 getEntry
public LDAPEntry getEntry()
Returns the entry of a server search response.
2.36 public class LDAPSearchResultReference
extends LDAPMessage
An LDAPSearchResultReference object encapsulates a continuation
reference from an asynchronous search operation.
2.36.1 getReferrals
public String[] getReferrals()
Returns any referral URLs in the object.
2.37 public class LDAPSearchResults
implements Enumeration
An LDAPSearchResults object is returned from a synchronous search
operation. It provides access to all results received during the
operation.
2.37.1 getCount
public int getCount()
Returns a count of the entries and exceptions in the search result.
If the search is asynchronous (batch size not 0), this reports the
number of results received so far.
2.37.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.
Expires April, 2001 [Page 102]
JAVA LDAP API April 2001
2.37.3 hasMoreElements
public boolean hasMoreElements()
Specifies whether or not there are more search results in the
enumeration. If true, there are more search results.
2.37.4 next
public LDAPEntry next() throws LDAPException
Returns the next result in the enumeration as an LDAPEntry. If
automatic referral following is disabled or a referral was not
followed, next() will throw an LDAPReferralException when the
referral is received.
2.37.5 nextElement
public Object nextElement()
Returns the next result in the enumeration as an Object. This the
default implementation of Enumeration.nextElement(). The returned
value may be an LDAPEntry or an LDAPException.
2.37.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:
Expires April, 2001 [Page 103]
JAVA LDAP API April 2001
comp An object that implements the LDAPEntryComparator
interface to compare two objects of type
LDAPEntry.
2.38 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.
2.38.1 makeSocket
public Socket makeSocket(String host, int port)
throws IOException, UnknownHostException
Returns a socket connected using the provided host name and port
number.
Parameters are:
host Contains a host identifier representing the IP
address of a host running an LDAP server to
connect to. See 2.6.8 for a discussion of valid
identifiers.
port Contains the TCP port number to connect to or
contact. The default LDAP port is 389.
2.39 public class LDAPSyntaxSchema
extends LDAPSchemaElement
The LDAPSyntaxSchema class represents the definition of a syntax. It
is used to discover the known set of syntaxes in effect for the
subschema. See [ATTR] for a description of syntax representation in
LDAP.
Note that though this extends LDAPSchemaElement, it does not use the
name or obsolete members, subsequently calls to getName always return
null and isObsolete always returns false. There is also no matching
getSyntaxNames method in LDAPSchema.
2.39.1 Constructors
public LDAPSyntaxSchema(String oid,
String description)
Expires April, 2001 [Page 104]
JAVA LDAP API April 2001
Constructs a syntax for adding to or deleting from the schema. Note
that adding and removing syntaxes is not typically a supported
feature of LDAP servers.
public LDAPSyntaxSchema(String raw)
Constructs a syntax from the raw String value returned on a schema
query for "LDAPSyntaxes".
Parameters are:
oid Object Identifier of the syntax - in dotted
numerical format.
description Optional description of the syntax.
raw The raw String value returned on a Directory
query for "ldapSyntaxes".
2.40 public interface LDAPUnsolicitedNotificationListener
An object that implements this interface can be notified when
unsolicited messages arrive from the server. A client registers the
object with LDAPConnection.addUnsolicitedNotificationListener.
2.40.1 messageReceived
public void messageReceived(LDAPExtendedResponse msg)
The method is called when an unsolicited message arrives from a
server, if the object has registered with
LDAPConnection.addUnsolicitedNotificationListener.
Parameters are:
msg An unsolicited message received from the server.
2.41 public class LDAPUrl
Encapsulates parameters of an LDAP Url query, as defined in
[LDAPURL]. An LDAPUrl object can be passed to LDAPConnection.search
to retrieve search results.
2.41.1 Constructors
public LDAPUrl(String url) throws MalformedURLException
Expires April, 2001 [Page 105]
JAVA LDAP API April 2001
Constructs a URL object with the specified string as URL.
public LDAPUrl(String host,
int port,
String dn)
Constructs a URL object with the specified host, port, and DN. This
form is used to create URL references to a particular object in the
directory.
public LDAPUrl(String host,
int port,
String dn,
String[] attrNames,
int scope,
String filter)
public LDAPUrl(String host,
int port,
String dn,
String[] attrNames,
int scope,
String filter,
boolean secure)
Constructs an LDAP URL with all fields explicitly assigned, to
specify an LDAP search operation.
Parameters are:
url An LDAP URL string, e.g.
"ldap://ldap.example.com:80/dc=example,dc=com?cn,
sn?sub?(objectclass=inetOrgPerson)".
host Host identifier of LDAP server, or null for
"localhost". See 2.6.8 for a discussion of valid
identifiers.
port Port number for LDAP server (use
LDAPConnection.DEFAULT_PORT for default port).
dn Distinguished name of the base object of the
search.
attrNames Names or OIDs of attributes to retrieve. Passing
a null array signifies that all user attributes
are to be retrieved. Passing a value of "*"
allows you to specify that all user attributes as
well as any specified operational attributes are
to be retrieved.
Expires April, 2001 [Page 106]
JAVA LDAP API April 2001
scope Depth of search (in DN namespace). Use one of
SCOPE_BASE, SCOPE_ONE, SCOPE_SUB from
LDAPConnection.
filter Search filter specifying the search criteria, as
defined in [FILTER].
secure True to create an LDAP URL of the "ldaps" type.
2.41.2 decode
public static String decode(String URLEncoded) throws
MalformedURLException
Decodes a URL-encoded string. Any occurrences of %HH are decoded to
the hex value represented. However, this method does NOT decode "+"
into " ". See [URL] for details on URL encoding/decoding.
Parameters are:
URLEncoded String to decode.
2.41.3 encode
public static String encode(String toEncode)
Encodes an arbitrary string. Any illegal characters are encoded as
%HH.
Parameters are:
toEncode String to encode.
2.41.4 getAttributeArray
public String[] getAttributeArray()
Returns an array of attribute names specified in the URL.
2.41.5 getAttributes
public Enumeration getAttributes()
Returns an Enumerator for the attribute names specified in the URL.
2.41.6 getDN
Expires April, 2001 [Page 107]
JAVA LDAP API April 2001
public String getDN()
Returns the distinguished name encapsulated in the URL, or null if
none is specified.
2.41.7 getExtensions
public String[] getExtensions ()
Returns any LDAP URL extensions specified, or null if none are
specified. Each extension is a type=value expression. The =value part
MAY be omitted. The expression MAY be prefixed with '!' if it is
mandatory for evaluation of the URL.
2.41.8 getFilter
public String getFilter()
Returns the search filter [LDAPURL], or the default filter -
(objectclass=*) - if none was specified.
2.41.9 getHost
public String getHost()
Returns the host name of the LDAP server to connect to.
2.41.10 getPort
public int getPort()
Returns the port number of the LDAP server to connect to.
2.41.11 getScope
public int getScope()
Returns the depth of search (in DN namespace) - one of SCOPE_BASE,
SCOPE_ONE, SCOPE_SUB from LDAPConnection.
2.41.12 getUrl
public String getUrl()
Returns a valid string representation of this LDAP URL.
Expires April, 2001 [Page 108]
JAVA LDAP API April 2001
2.41.13 isSecure
public boolean isSecure()
Returns true if the URL is of the type ldaps (LDAP over SSL, a
predecessor to startTLS).
3. Implementation Considerations
3.1 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
setConstraints and getConstraints methods. Either a single
LDAPControl or an array may be specified, e.g.
LDAPControl control = new LDAPControl( type, critical, vals );
LDAPConstraints cons = ld.getConstraints();
cons.setServerControls( control );
ld.setConstraints( cons );
or
LDAPControl[] controls = new LDAPControl[ATTR];
controls[0] = new LDAPControl( type0, critical0, vals0 );
controls[X500] = new LDAPControl( type1, critical1, vals1 );
LDAPConstraints cons = ld.getConstraints();
cons.setServerControls( controls );
ld.setConstraints( cons );
Server controls returned to a client as part of the response to a
synchronous operation can be obtained with
LDAPConnection.getResponseControls(). Controls returned on an
asynchronous operation are available with LDAPMessage.getControls().
Support for specific controls is defined in a package "controls"
subordinate to the main LDAP package.
3.2 Referral handling and exceptions
Asynchronous requests
Expires April, 2001 [Page 109]
JAVA LDAP API April 2001
No automatic referral following is supported for asynchronous
requests.
No LDAPExceptions are thrown except in the case of CONNECT_ERROR. The
Throwable causing the CONNECT_ERROR can be retrieved with
LDAPConnection.getCause().
The application receives an LDAPResponse with a result code of
REFERRAL or the application receives an LDAPSearchResultReference.
Synchronous requests
Behavior depends on if automatic referral following is enabled, and
if enabled, if an LDAPReferralHandler is provided by the application.
- Automatic referral following is "false"
An LDAPException is thrown for any non-zero result code.
An LDAPException is thrown on connection for local failures.
An LDAPReferralException is thrown if the result code is
REFERRAL. It contains the referral strings.
An LDAPReferralException is thrown upon receipt of an
LDAPSearchResultReference. It contains the referral strings.
This is not an error, there may be more data to retrieve. The
API will throw an LDAPReferralException for each
LDAPSearchResultReference it receives during a search request.
- Automatic referral following is "true" and either no
LDAPReferralHandler is registered in LDAPConstraints, or an
LDAPRebind LDAPReferralHandler is registered in LDAPConstraints
LDAPExceptions are thrown as usual if errors occur during the
normal processing of the command, i.e. NO_SUCH_OBJECT,
NO_SUCH_ATTRIBUTE, etc.
An LDAPReferralException is thrown only if the API could not
connect and bind to any referral URL in the list of URLs
included in an individual REFERRAL result or
LDAPSearchResultReference.
When problems occur during the establishment of an authenticated
connection by the API during automatic referral following, the
LDAPReferralException will contain the last tried URL String of
the server the API attempted to connect/bind to (the referral
can be retrieved with getFailedReferral()), and the Throwable
that caused the Exception (which can be retrieved with
getCause()).Some possible failures are IOException on the
Expires April, 2001 [Page 110]
JAVA LDAP API April 2001
connection, MalformedURLException on the referral string, or
authentication failures on the bind.
Upon receipt of an LDAPReferral exception, the application knows
that the API was not able to connect to any of the servers in
the referral list (which can be retrieved with getReferrals())
and so was not able to follow the referral. The error indicated
by getCause() occurred on the referral indicated with
getFailedReferral(). In the case of search, the data starting at
the indicated base of the referred to server is missing from the
results.
- Automatic referral following is "true", and an LDAPBind
LDAPReferralHandler is registered in LDAPConstraints
LDAPExceptions are thrown as usual if errors occur during the
normal processing of the command, i.e. NO_SUCH_OBJECT,
NO_SUCH_ATTRIBUTE, etc.
An LDAPReferralException is thrown only if the LDAPBind handler
throws an exception.
Upon receipt of an LDAPReferral exception, the application knows
that the LDAPBind object was not able or not willing to connect
to any of the servers in the referral list and so was not able
to follow the referral. The list of referrals that failed is
available with getReferrals() and the last failed referral with
getFailedReferral(). The exception thrown by LDAPBind is
available with getCause().
3.3 Notice of disconnection
If a notice of disconnection is received by a connection object, the
object MUST close the connection without accepting or sending
additional messages. Any clones of the object are disconnected as a
consequence of closing the connection.
3.4 Level of compatibility
Implementations of the API are to be binary compatible. Any
implementation MUST behave as defined above with any application
written to the API specification.
3.5 Invalid responses
If a message is received by an API implementation from the server and
the message cannot be interpreted as an LDAP PDU, an LDAPException
MUST be thrown with a result code of INVALID_RESPONSE.
Expires April, 2001 [Page 111]
JAVA LDAP API April 2001
4. 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.
If a TLS session is terminated by the server but the client TLS
provider and LDAP API implementation continue to use the socket
rather than closing it, the application is notified through an
LDAPException on the first operation request subsequent to
termination of the TLS session.
An interface to using SASL for configurable authentication and
session protection is provided, but implementations are outside the
scope of this document. Implementations of this API MUST ensure that
a SASL provider is configured to comply with the minimal security
guidelines of RFC 2829 [AUTH].
Implementations of this API SHOULD be cautious when handling
authentication credentials. In particular, keeping long-lived copies
of credentials without the application's knowledge is discouraged.
5. Acknowledgements
The proposed API builds on earlier work done in collaboration with
Thomas Kwan and Stephan Gudmundson, then of NCware Technologies Corp.
It also includes suggestions by Steven Merrill of Novell and
benefited from extensive review and comments by Kurt Zeilenga of
OpenLDAP. Parts of the overview of the LDAP model are taken from
draft-ietf-ldapext-ldap-c-api.
6. Bibliography
[X500] The Directory: Overview of Concepts, Models, and Services.
CCITT, Recommendation X.500.
[ATTR] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight
Directory Access Protocol: Attribute Syntax Definitions",
RFC 2252, December 1997
[FILTER] T. Howes, "A String Representation of LDAP Search Filters,"
RFC 2254, December 1997.
[DN] S. Kille, " UTF-8 String Representation of Distinguished
Names," RFC 2253, December 1997.
[LDAPv3] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
Protocol (v3)", RFC 2251, December 1997.
Expires April, 2001 [Page 112]
JAVA LDAP API April 2001
[LDAPURL] T. Howes, M. Smith, "An LDAP URL Format", RFC 2255,
December 1997.
[URL] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource
Locators (URL)", RFC 1738, December 1994.
[LANG] H. Alvestrans, "Tags for the Identification of Languages", RFC
1766, March 1995.
[TLS] T. Dierks, C. Allen, "The TLS Protocol", RFC 2246, January
1999.
[LDAPTLS] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory
Access Protocol (v3): Extension for Transport Layer Security",
RFC 2830, May 2000.
[SASL] J. Myers, "Simple Authentication and Security Layer (SASL)",
RFC 2222, October 1997.
[AUTH] M. Wahl, H. Alvestrand, J. Hodges, R. Morgan, "Authentication
Methods for LDAP", RFC 2829, May 2000
[JAVA] J. Gosling, B. Joy, Guy L., Jr. Steele, "The Java Language
Specification", Addison-Wesley, September 1996
[IPv6] R. Hinden, B. Carpenter, L. Masinter, "Format for Literal IPv6
Addresses in URL's", RFC 2732, December 1999
[JAVASASL] "Java SASL Specification", Java Community Process, JSR28
[KEYWORDS] "Key words for use in RFCs to Indicate Requirement
Levels", Bradner, S., RFC 2119, March 1997
7. Authors' Addresses
Rob Weltman
Coscend Corp.
3290 W. Bayshore Road
Palo Alto, CA 94303
+1 650 461 1708
robw@coscend.com
Christine Tomlinson
Innosoft International, Inc.
8911 Capital of Texas Highway
Suite 4140
Austin, TX US 78759
+1 512 231 1600
Expires April, 2001 [Page 113]
JAVA LDAP API April 2001
christine.tomlinson@innosoft.com
Miodrag Kekic
Netscape Communications Corp.
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
+1 650 937-5663
miodrag@netscape.com
Steven Sonntag
Novell, Inc.
1800 South Novell Place
Provo, UT 84606
USA
+1 801 861 7097
vtag@novell.com
Jim Sermersheim
Novell, Inc.
1800 South Novell Place
Provo, UT 84606
USA
+1 801 861 3088
jimse@novell.com
Mark Smith
Netscape Communications Corp.
501 E. Middlefield Rd.
Mountain View, CA 94043
USA
+1 650 937-3477
mcs@netscape.com
Tim Howes
Loudcloud, Inc.
599 N. Mathilda Ave.
Sunnyvale, CA 94086
USA
+1 650 321-4565 x111
howes@loudcloud.com
Expires April, 2001 [Page 114]
JAVA LDAP API April 2001
8. Appendix A - Sample java LDAP programs
8.1 Java LDAP programs using synchronous methods
import org.ietf.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 = "dc=example,dc=com";
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();
Expires April, 2001 [Page 115]
JAVA LDAP API April 2001
Enumeration enumAttrs = findAttrs.getAttributes();
System.out.println( "Attributes: " );
/* 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.
Note: we are assuming all values are UTF-8
strings
*/
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, 2001 [Page 116]
JAVA LDAP API April 2001
import org.ietf.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,dc=example,dc=com";
String MY_PASSWORD = "MysteryLady";
ld.bind( MY_NAME, MY_PASSWORD );
/* Prepare to change my email address */
LDAPAttribute attrEmail =
new LDAPAttribute( "mail", "babs@example.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, 2001 [Page 117]
JAVA LDAP API April 2001
import org.ietf.ldap.*;
import java.util.*;
public class ShowSchema {
public static void main( String[] args )
{
LDAPConnection ld = new LDAPConnection();
try {
/* Connect to server */
String MY_HOST = "localhost";
int MY_PORT = 389;
ld.connect( MY_HOST, MY_PORT );
/* Fetch the schema (anonymous is okay for reading) */
LDAPSchema schema = new LDAPSchema();
schema.fetchSchema( ld );
/* What is the definition of "userPassword"? */
LDAPAttributeSchema a =
schema.getAttribute( "userpassword" );
if ( a != null ) {
String syntax = a.getSyntaxString();
String syntaxString = "string";
if ( syntax.equals(BINARY_SYNTAX) )
syntaxString = "binary";
else if (syntax.equals(INTEGER_SYNTAX) )
syntaxString = "integer";
String single = "multi-valued";
if ( a.isSingleValued() )
single = "single-valued";
System.out.println( "userPassword. " +
"OID = " + a.getID() +
", type = " + syntaxString +
", " + single );
);
/* What are the possible attributes for "person"? */
LDAPObjectClassSchema o =
schema.getObjectClass( "person" );
if ( o != null ) {
Enumeration required = o.getRequiredAttributes();
Enumeration optional = o.getOptionalAttributes();
System.out.println(
"Required attributes for person:" );
while( required.hasMoreElements() )
System.out.println( " " +
(String)required.nextElement() );
System.out.println(
"Optional attributes for person:" );
while(optional.hasMoreElements() )
System.out.println( " " +
(String) optional.nextElement() );
Expires April, 2001 [Page 118]
JAVA LDAP API April 2001
);
} catch( LDAPException e ) {
System.out.println( "Error: " + e.toString() );
}
/* Done, so disconnect */
if ( ld.isConnected() )
ld.disconnect();
}
protected static final String BINARY_SYNTAX =
"1.3.6.1.4.1.1466.115.121.1.5";
protected static final String INTEGER_SYNTAX =
"1.3.6.1.4.1.1466.115.121.1.27";
}
Expires April, 2001 [Page 119]
JAVA LDAP API April 2001
8.2 Java LDAP programs using asynchronous methods
import org.ietf.ldap.*;
import java.util.*;
public class SearchJensen {
public static void main( String[] args ) {
try {
LDAPConnection ld = new LDAPConnection();
/* Connect to server */
String MY_HOST = "localhost";
int MY_PORT = 389;
ld.connect( MY_HOST, MY_PORT );
/* Asynchronous authentication */
LDAPResponseListener r =
ld.bind( "uid=admin, o=Airius.com",
"password", null );
/* Do something else, just to show that we're not
blocked yet */
System.out.println( "Started authenticating" );
/* Wait until it completes */
LDAPResponse response = (LDAPResponse)r.getResponse();
int resultCode = response.getResultCode();
if (resultCode != LDAPException.SUCCESS) {
throw new LDAPException ("error result", resultCode,
response.getErrorMessage(),
response.getMatchedDN());
}
/* search for all entries with surname of Jensen */
String MY_FILTER = "(sn=Jensen)";
String MY_SEARCHBASE = "dc=example,dc=com";
LDAPSearchListener l =
ld.search( MY_SEARCHBASE,
ld.SCOPE_ONE,
MY_FILTER,
null,
false,
null,
(LDAPSearchListener)null );
/* Loop on results until finished */
LDAPMessage msg;
while( (msg = l.getResponse()) != null ) {
if ( msg instanceof LDAPSearchResultReference ) {
String[] urls =
(LDAPSearchResultReference)msg).getReferrals();
// Do something with the referrals...
Expires April, 2001 [Page 120]
JAVA LDAP API April 2001
} else if ( msg instanceof LDAPSearchResult ) {
LDAPEntry entry =
((LDAPSearchResult)msg).getEntry();
// The rest of the processing is the same as for
// a synchronous search
System.out.println( entry.getDN() );
} else {
// A search response
LDAPResponse res = (LDAPResponse)msg;
int status = res.getResultCode();
if ( status == LDAPException.SUCCESS ) {
// Nothing to do
} else {
String err =
LDAPException.errorCodeToString(status);
throw new LDAPException(
err,
status,
res.getErrorMessage(),
res.getMatchedDN() );
}
}
}
} catch ( LDAPException e ) {
System.err.println( e.toString() );
}
/* Done, so disconnect */
if ( ld.isConnected() ) {
ld.disconnect();
}
}
}
Expires April, 2001 [Page 121]
JAVA LDAP API April 2001
import org.ietf.ldap.*;
import java.util.*;
/* This example multiplexes the input from three different servers */
public class MultiplexServers {
public static void main( String[] args )
{
try {
LDAPConnection [] ld = new LDAPConnection [FILTER];
String[] hosts = { "foo1", "foo2", "foo3" };
int[] ports = { 389, 389, 2018 }
String[] bases = { "dc=example,dc=com",
"o=example.com",
"dc=example2,dc=com" };
/* search for all entries with surname of Jensen */
String MY_FILTER = "(sn=Jensen)";
for( int i = 0; i < ld.length; i++ ) {
ld[i] = new LDAPConnection ();
/* Connect to server */
ld[i].connect( hosts[i], ports[i] );
}
/* Get a response listener for one search */
LDAPSearchListener l =
ld[0].search( bases[0],
ld.SCOPE_SUB,
MY_FILTER,
null,
false,
(LDAPSearchListener)null );
/* Share the listener */
for( i = 1; i < ld.length; i++ ) {
ld[i].search( bases[i],
ld[i].SCOPE_SUB,
MY_FILTER,
null,
false,
l );
}
/* Loop on results until finished */
LDAPMessage msg;
while( (msg = l.getResponse()) != null ) {
/* The rest is the same as in the previous example */
/* ... */
Expires April, 2001 [Page 122]
JAVA LDAP API April 2001
import org.ietf.ldap.*;
import java.util.*;
/* This example multiplexes the input from three searches in
different subtrees of the same server */
public class MultiplexTrees {
public static void main( String[] args )
{
try {
LDAPConnection ld = new LDAPConnection ();
/* Connect to server */
String MY_HOST = "localhost";
int MY_PORT = 389;
ld.connect( MY_HOST, MY_PORT );
String MY_FILTER = "(sn=Jensen)";
String[] bases = { "dc=example,dc=com",
"o=example.com",
"dc=example2,dc=com" };
/* Get a response listener for one search */
LDAPSearchListener l =
ld.search( bases[0],
ld.SCOPE_SUB,
MY_FILTER,
null,
false,
(LDAPSearchListener)null );
/* Share the listener */
for( i = 1; i < bases.length; i++ ) {
ld.search( bases[i],
ld.SCOPE_SUB,
MY_FILTER,
null,
false,
l );
}
/* The rest is the same as in the MultiplexServers
example */
/* ... */
Expires April, 2001 [Page 123]
JAVA LDAP API April 2001
import org.ietf.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, dc=example,dc=com";
String MY_PASSWORD = "MysteryLady";
ld.bind( MY_NAME, MY_PASSWORD );
/* Prepare to change my email address */
LDAPAttribute attrEmail =
new LDAPAttribute( "mail", "babs@example.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, 2001 [Page 124]
JAVA LDAP API April 2001
9. Appendix B - Revision history
9.1 Changes from ldap-java-api-13.txt
Notice of disconnection, Invalid responses, Level of compatibility
New section
Result codes
Added INVALID_RESPONSE, AMBIGUOUS_RESPONSE
Removed PARAM_ERROR
LDAPConnection
Removed getAuthenticationPassword()
Added bind() signatures that take a byte array for password
bind() signatures for SASL take an authzId parameter
disconnect() may take an LDAPConstraints parameter
read() throws LDAPException with AMBIGUOUS_RESPONSE if there is
more than one result
LDAPConstraints
Removed getReferralHandler
LDAPRebindAuth
Added a signature of the constructor which takes byte[] as
parameter
getPassword() returns byte[] instead of String
LDAPReferralException
Clarified that getReferrals() must return LDAP URL strings with
the scope rewritten if necessary (for SearchResultReferences on
search continuation).
LDAPDN
Added normalize() and isValid().
Expires April, 2001 [Page 125]
JAVA LDAP API April 2001
LDAPUnsolicitedNotificationListener
The argument to messageReceived() is LDAPExtendedResponse and
not LDAPMessage.
Security Considerations
Added implementation guidelines
General
All classes and methods in alphabetical order
Many clarifications and editorial changes
9.2 Changes from ldap-java-api-12.txt
Abstract
Removed references to RFC 1823 and to an earlier draft on an
asynchronous interface.
LDAPConnection
Under clone(), added a listing of which methods affect an
individual clone and which ones affect all related clones.
LDAPException
Can take Throwable as root exception argument in an additional
constructor signature. Added getCause() to return the root
exception. Removed reference to LDAP_PARTIAL_RESULTS among
result codes.
LDAPBind
bind() throws LDAPReferralException instead of LDAPException.
LDAPReferralException
Can take Throwable as root exception argument instead of
LDAPException. getFailureException() was removed and replaced
by getCause() in LDAPException. Added getFailedReferral() and
setFailedReferral().
Expires April, 2001 [Page 126]
JAVA LDAP API April 2001
LDAPControl
Removed newInstance(). An implementation of the API can
instantiate a control using the LDAPControl constructor.
Removed a sentence saying that LDAPv2 doesn't support controls.
Referral handling
Added section outlining the handling of exceptions on
referrals.
References
Added references to RFCs 2222 and 2830.
Host names
May be IPv6 references as well as hostnames or IPv4 addresses.
LDAPMessage
Restored the values of the message types to correspond to the
message type values in ldap-java-api-11.txt.
LDAPEntry
getAttribute returns a single attribute.
Unsolicited notifications in LDAPConnection
Removed getUnsolicitedNotifications and
setUnsolicitedNotifications. Added
addUnsolicitedNotificationListener and
removeUnsolicitedNotificationListener. Added interface
LDAPUnsolicitedNotificationListener.
9.3 Changes from ldap-java-api-11.txt
LDAPConnection
Eliminated the interfaces (LDAPv2 and LDAPv3) that
LDAPConnection implemented.
Expires April, 2001 [Page 127]
JAVA LDAP API April 2001
Eliminated setOption and getOption (there are corresponding
properties in LDAPConstraints and LDAPSearchConstraints).
Removed the signatures of connect which took DN, password, and
protocol version as arguments. The previous signatures were
utility methods that combined connect and bind.
Added a signature of extendedOperation which takes
LDAPConstraints as argument.
Added isTLS.
Added getProtocolVersion.
Added signatures of abandon which take LDAPConstraints as
argument.
extendedOperation returns LDAPExtendedResponse, not
LDAPExtendedOperation.
Added signatures of SASL bind that take LDAPConstraints as
argument.
Added getSaslBindProperties.
Added getSaslBindCallbackHandler.
Added getUnsolicitedNotifications and
setUnsolicitedNotifications.
The default protocol version to bind with is LDAPv3, not
LDAPv2.
Constants: LDAP_DEREF_NEVER, etc changed to DEREF_NEVER, etc.
Values of DEREF_SEARCHING and DEREF_FINDING corrected to those
of RFC 2251. The values are now defined in
LDAPSearchConstraints instead of in LDAPConnection.
LDAPControl
Added setValue.
LDAPExtendedOperation
Added setValue.
LDAPSearchResultReference
Changed getURLs to getReferrals, which returns String[].
Expires April, 2001 [Page 128]
JAVA LDAP API April 2001
LDAPUrl
Added method isSecure.
Added constructors that take a boolean for isSecure.
LDAPReferralException
Added getReferralFailureException.
Changed getURLs to getReferrals, which returns String[].
LDAPConstraints
Takes a new interface LDAPReferralHandler as parameter, instead
of LDAPBind and LDAPRebind.
Changed getReferrals to getReferralFollowing.
Changed setReferrals to setReferralFollowing.
LDAPReferralHandler
New common ancestor to LDAPBind and LDAPRebind.
LDAPListener
New common ancestor to LDAPSearchListener and
LDAPResponseListener.
LDAPSearchListener
Implements LDAPListener.
Added signature of isResponseReceived and of getResponse that
takes a message ID as parameter.
Added isComplete.
LDAPResponseListener
Implements LDAPListener.
Added signatures isResponseReceived and getResponse that take a
message ID as parameter.
Expires April, 2001 [Page 129]
JAVA LDAP API April 2001
LDAPBind
Changed the signature of bind to return LDAPConnection instead
of void, and take an LDAP URL string list as argument.
LDAPException
Defined the values of symbolic result codes generated by the
interface. Added a constructor that takes matchedDN as
parameter.
LDAPMessage
Redefined the values of the message types to correspond to the
message type values in [LDAPv3].
9.4 Changes from ldap-java-api-10.txt
Overview of the LDAP model
Allowed for character set conversion from/to T.61 (in addition
to UTF-8).
LDAPConnection
Added startTLS. Added STRING_FORMAT option to setOption. Added
numerical values to options in setOption and search. Changed
REFERRALS_AUTHENTICATION to REFERRALS_REBIND_PROC. Clarified
that getAuthenticationPassword returns null if no simple bind
has been performed. Added asynchronous methods (from [TLS]).
LDAPConstraints
Default for setHopLimit is 10, not 5.
LDAPUrl
Added getScope and getExtensions.
Schema classes
Added parameters to constructors (aliases, obsolete,
collective).
Various classes
Expires April, 2001 [Page 130]
JAVA LDAP API April 2001
Removed all "synchronized" qualifier on methods. Added a
statement that implementations should ensure thread-safety.
9.5 Changes from ldap-java-api-09.txt
Overview of LDAP API use
Clarifications were added on the behavior of the SDK for null
values of LDAPConstraints and for a DN.
LDAPAttributeSet
Return type of getAttribute is LDAPAttribute, not
LDAPAttribute[].
LDAPV2
Added convenience method of add that does not take
LDAPConstraints, added read method that does take
LDAPSearchConstraints.
Error Codes
Changed to Result Codes. Added TLS_NOT_SUPPORTED.
LDAPSearchResults
Clarified in declaration that it implements Enumeration.
LDAPV3
Added constants NO_ATTRS and ALL_USER_ATTRS.
Schema classes
Added LDAPDITContentRuleSchema, LDAPDITStructureRuleSchema,
LDAPMatchingRuleUseSchema, LDAPNameFormSchema, LDAPSyntaxSchema.
9.6 Changes from ldap-java-api-08.txt
Standards track
Expires April, 2001 [Page 131]
JAVA LDAP API April 2001
Added intended category to first page header.
SASL references
Removed all references to a Java SASL internet draft.
LDAPv2
Removed static methods search(LDAPUrl url). The methods are
still present in LDAPConnection.
9.7 Changes from ldap-java-api-07.txt
LDAPAttributeSchema
Removed getAliases() because it is already defined in the
superior class LDAPSchemaElement. Removed getSyntax() which
returned an integer.
LDAPConnection
Added getAuthenticationMethod().
LDAPSchemaElement
Changed getOID() to getID().
9.8 Changes from ldap-java-api-06.txt
LDAPAttributeSchema
Added a constructor that takes the attribute syntax as a String,
an optional superior attribute type, and an optional list of
aliases. Removed previous constructor.
Added getSuperior()and getSyntaxString().
LDAPConnection
Added getInputStream()getOutputStream(), setInputStream()
(2.6.36), and setOutputStream(). They are used when establishing
a security layer with SASL, and may also be used to interpose a
proxy.
LDAPDN
Added equals().
Expires April, 2001 [Page 132]
JAVA LDAP API April 2001
LDAPException
Added additional error codes defined in [URL].
LDAPMatchingRuleSchema
Added a constructor that takes the attribute syntax as a String
and an optional list of aliases. Removed previous constructor.
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. Removed previous constructor.
Added getSuperiors()and getType(). Removed getSuperior().
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.
Added getAliases(), getQualifier(), getQualiferNames(),
isObsolete(), and setQualifier().
9.9 Changes from ldap-java-api-05.txt
LDAPConnection
Distinguished between getConstraints() and
getSearchConstraints(), and between setConstraints() and
setSearchConstraints().
LDAPConstraints
LDAPBind and LDAPRebind should not be specified in the same
constructor. Added setClientControls().
LDAPSearchConstraints
LDAPBind and LDAPRebind should not be specified in the same
constructor.
Expires April, 2001 [Page 133]
JAVA LDAP API April 2001
LDAPControl
newInstance() is now static.
LDAPv3
Changed the signature of the bind() methods to match the Java
SASL Internet Draft.
9.10 Changes from ldap-java-api-04.txt
LDAPAttribute
Added getByteValueArray() and getStringValueArray().
LDAPCompareAttrNames
Added getLocale() and setLocale().
LDAPSchemaElement
Added modify().
LDAPSchemaElement
Added fetchSchema(LDAPConnection, String).
9.11 Changes from ldap-java-api-03.txt
LDAPBind
New interface, to support sophisticated reauthentication
mechanisms.
LDAPControl
Added methods register() and newInstance(), to support dynamic
registration and instantiation of server response controls.
LDAPConstraints
Expires April, 2001 [Page 134]
JAVA LDAP API April 2001
Separated interface time limit from server search time limit.
Moved all search-only constraints to LDAPSearchConstraints.
LDAPRebind
Reverted back to original name, instead of LDAPReauthentication
as it was in the previous draft.
LDAPRebindProc
Reverted back from LDAPCredentials.
LDAPSearchConstraints
Reinstated this class, to represent all constraints applicable
to a search. LDAPConstraints (which it extends) only represents
common constraints for all operations.
LDAPSearchResults
Added getResponseControls().
LDAPv2
Added abandon(). Separated interface time limit from server
search time limit. Changed authenticate() to bind().
LDAPv3
Changed authenticate() to bind().
9.12 Changes from ldap-java-api-02.txt
LDAPSearchConstraints
Renamed to LDAPConstraints, since it can be applied to
operations other than search.
LDAPRebind
Renamed to LDAPReauthentication. Added a definition of its
single method.
LDAPRebindProc
Expires April, 2001 [Page 135]
JAVA LDAP API April 2001
Renamed to LDAPCredentials.
9.13 Changes from ldap-java-api-01.txt
LDAPAttribute
Added a copy constructor.
Added support for subtypes, and for language subtypes in
particular.
LDAPAttributeSet
LDAPAttributeSet implements Cloneable.
Added getSubset() for subtype support.
LDAPDN
Added support for escaping and unescaping an RDN.
LDAPException
Added the SASL_BIND_IN_PROGRESS error code.
LDAPSearchResults
Added getCount(), to report the number of results returned.
LDAPConnection
Added a signature that passes LDAPConstraints to read(LDAPURL).
LDAPv2
Added signatures that pass LDAPConstraints to the following
methods:
add()
compare()
modify()
read()
rename()
LDAPv3
Expires April, 2001 [Page 136]
JAVA LDAP API April 2001
Removed "Preferred Language", because it has been dropped from
the extension work.
Added a signature that passes LDAPConstraints to rename().
Expires April, 2001 [Page 137]
| PAFTECH AB 2003-2026 | 2026-04-24 02:54:00 |