Network Working Group Christine Tomlinson INTERNET-DRAFT Innosoft International, Inc. Kenneth Suter Innosoft International, Inc. Mark Wahl Innosoft International, Inc. February 25, 1999 The Java LDAP Application Program Interface draft-ietf-ldapext-alt-ldap-java-api-00.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 Engineering 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. Distribution of this document is unlimited. Please send comments to the authors or the LDAPEXT mailing list, ietf-ldapext@netscape.com. Copyright Notice: Copyright (C) The Internet Society (1999). All Rights Reserved. ABSTRACT This document defines a java language application program interface to the lightweight directory access protocol (LDAP), in the form of a class library. It provides an alternative to the draft by R. Weltman, T. Howes, M. Smith, C. Ho in describing significant additions and differences in design. Expires 8/99 [Page 1] JAVA LDAP API February 1999 1. Overview 1.1 Preface This document describes a Java(tm) API to the Light Weight Directory Access Protocol(LDAP). It specifies an API for LDAPv2 as specified in Internet RFC 1777, and LDAPv3 as specified in Internet RFCs 2251, 2252, 2253, 2254, 2255, and 2256. 1.2 Introduction The Java API offers users a simple, robust way of creating applications that interact with Innosoft’s and other vendor's LDAP servers (protocol versions 2 or 3). In addition to properties inherent in the Java language itself (object-oriented, robust, secure, architecture neutral, portable, multi-threaded, and dynamic), the Java API uses a simple object hierarchy that makes it easy for application designers with at least basic knowledge of LDAP to get started right away. In addition, the Java API closely implements the LDAPv3 definitions outlined in RFCs 2251 through 2256. 1.2.1 Summary of Packages org.ietf.ldap Provides classes that model LDAP directory entries and their components, as well as components of the protocol that apply to both clients and servers. org.ietf.ldap.client Provides classes that model LDAP protocol components of that are particularly relevant to client-side applications. org.ietf.ldap.ldif Provides classes that implement reading and writing LDAP Interchange Format streams. org.ietf.ldap.schema Provides classes that implement the components of the schema on LDAP servers representing Attributes, Objectclasses, and MatchingRules. 2. Package org.ietf.ldap 2.0.1 Description Provides interfaces and classes that model LDAP directory entries and their components, as well as components of the protocol that apply to both clients and servers. The org.ietf.ldap package provides directory entry, schema, filter, and exception abstractions . Most of the classes will be familiar to designers that have worked with Expires 8/99 [Page 2] JAVA LDAP API February 1999 LDAP before. There are several classes that are intended to be extended that model protocol elements that support extension of the protocol: Control ExtendedResponse Enum 2.1 Interface org.ietf.ldap.Controls public abstract interface Controls Defines a collection of Control objects to be used to transfer ldap controls in requests as well as to receive controls in responses. 2.1.1 size public int size() Return the number of Control objects in the collection 2.1.2 get public Control get(java.lang.String ctrlId) Return the Control with the corresponding control type OID in String form. If no such Control exists then null is returned. 2.1.3 get public Control get(OID ctrlId) Return the Control with the corresponding control type OID. If no such Control exists then null is returned. 2.1.4 getAll public java.util.Enumeration getAll() Return an Enumeration of the Control objects in the collection. 2.1.5 toArray public Control[] toArray() Return an array of the Controls in the collection. 2.1.6 getIds public java.util.Enumeration getIds() Returns an Enumeration of the control type OIDs for the Controls in the collection. 2.1.7 put Expires 8/99 [Page 3] JAVA LDAP API February 1999 public Control put(Control ctrl) Add a Control to the collection. If there is a Control of the same type in the collection it is replaced by the given Control and the previous Control is returned as the result of the method; otherwise null is returned. 2.1.8 remove public Control remove(java.lang.String ctrlId) Removes the Control with the given control type OID represented as a String. The removed Control is returned as the result of the method. If no such Control exists then null is returned and no other action is taken. 2.1.9 remove public Control remove(OID ctrlId) Removes the Control with the given control type OID. The removed Control is returned as the result of the method. If no such Control exists then null is returned and no other action is taken. 2.2 Interface org.ietf.ldap.EntityEnumeration public abstract interface EntityEnumeration extends java.util.Enumeration This interface defines a means of enumerating the entries returned by LDAP operations such as search(...). It extends the Enumeration interface so that Exceptions specific to the LDAP protocol and its interface components may be thrown from the operations: next(), nextEntry() and hasMore(). In some cases an application may perform processing directly on Referrals as well as the Entries that are returned from a search or other operation. In this case the next() method is used. If the nextEntry() method is used and a Referral is next among the objects of the EntityEnumeration then a ReferralException is thrown. The operations of the interface Enumeration are also available so that components that expect an Enumeration may be used with as well. In some places in the LDAP protocol an exceptional resultCode may be returned, for example, sizeLimitExceeded. In these cases the result entries may be consumed long after the result has been received. In this situation a SizeLimitExceededException will be thrown. If the nextElement () method is used and the next() method would throw an LDAPException then the NoSuchElementException is thrown instead. 2.2.1 hasMore public boolean hasMore() Expires 8/99 [Page 4] JAVA LDAP API February 1999 throws LDAPException Returns true if more entries are available, false otherwise. This operation may signal an LDAPException in the event that all entries have been returned and an exceptional condition was returned from one or more servers during processing of the search. Returns: true if more results are available, false otherwise. 2.2.2 nextEntry public Entry nextEntry() throws LDAPException Returns the next Entry or throws an LDAPException if all entries have been processed and an exceptional condition occurred during processing of the search. Returns: the next Entry in the EntityEnumeration. Throws: LDAPException - if an exceptional result was returned during processing. 2.2.3 next public Entity next() throws LDAPException Returns the next Entity (Entry or Referral) or throws an LDAPException if all entries have been processed and an exceptional condition occurred during processing of the search. This method is provided for those cases in which both Entry and Referral objects are handled directly by an application. In the case that referral handling is performed implicitly by the interface, nextEntry() is the preferred method to use to access the EntityEnumeration. Returns: the next Entry in the EntityEnumeration. Throws: LDAPException - if an exceptional result was returned during processing. 2.3 Interface org.ietf.ldap.SocketHandler public abstract interface SocketHandler The SocketHandler interface is typically implemented by classes that provide TLS support. The LDAP protocol requires the use of the Start TLS method of establishing a TLS session. This implies that a connection from the client to the server has already been established before it is known and agreed that TLS will be used. This interface serves to separate the implementation of the Connection Expires 8/99 [Page 5] JAVA LDAP API February 1999 mechanism from the details of a given implementation of TLS support. 2.3.1 connectSocket public java.net.Socket connectSocket(java.lang.String host, int port, org.ietf.ldap.apdu.Connection connection) throws LDAPException This method is called from the Connection to establish a Socket over which the client will interact with the LDAP server. 2.4 Class org.ietf.ldap.AliasDeref public final class AliasDeref extends Enum Enumerates the possible choices for controlling the de-referencing of aliases during search operations: NEVER, SEARCHING, FINDING, and ALWAYS. 2.4.1 Fields public static final AliasDeref NEVER Never follow aliases. public static final AliasDeref SEARCHING Follow aliases only when searching, once the base entry has been located. public static final AliasDeref FINDING Follow aliases when finding the base entry. public static final AliasDeref ALWAYS Always follow aliases. 2.4.2 toAliasDeref public static AliasDeref toAliasDeref(int code) Given an integer code for a value of AliasDeref, returns the unique instance of AliasDeref that corresponds to that code or null. Parameters: code - encoded value of an instance of AliasDeref. Returns: corresponding instance of AliasDeref or null. 2.4.3 toName public static java.lang.String toName(int code) Given an integer code returns the name of the corresponding value of Expires 8/99 [Page 6] JAVA LDAP API February 1999 AliasDeref Parameters: code - encoded value to lookup. Returns: the name or null. 2.5 Class org.ietf.ldap.AssertionValue public abstract class AssertionValue An AssertionValue is used in both AttributeValueAssertions and as the matchValue of a MatchingRuleAssertion (although this latter is not currently reified as a class). An AssertionValue may be encoded as either a string or a binary encoding represented via a byte[]. The syntax of the AssertionValue is determined by the MatchingRuleAssertion in which it occurs. 2.5.1 make public static AssertionValue make(byte[] val) Returns an AssertionValue represented by the byte[]. Parameters: val - the byte[] representation Returns: the AssertionValue 2.5.2 make public static AssertionValue make(java.lang.String val) Returns an AssertionValue represented by the String. Parameters: val - the String representation Returns: the AssertionValue 2.5.3 numBytes public abstract int numBytes() The size of the AssertionValue in bytes. If the value was constructed using a String then the size is reported in terms of the bytes that occur in a UTF-8 encoding of the String value. Returns: the size of the AssertionValue in bytes Expires 8/99 [Page 7] JAVA LDAP API February 1999 2.5.4 numChars public abstract int numChars() The size of the AssertionValue in chars. If the value was constructed using a byte[] then it is assumed to have been a UTF-8 encoding of a UCS-2 String. Returns: the size of the AssertionValue in chars 2.5.5 toString public abstract java.lang.String toString() Returns the String representation of the AssertionValue. If the value used to construct the AssertionValue was a byte[] then it is converted to a String via UTF-8. If the byte[] does not encode a String via UTF-8 then null is returned. Returns: the String representation of this AssertionValue. 2.5.6 toBytes public abstract byte[] toBytes() Returns the byte[] representation of the AssertionValue. If the value used to construct the AssertionValue was a String then it is converted to a byte[] via UTF-8. Returns: the byte[] representation of this AssertionValue. 2.6 Class org.ietf.ldap.Attribute public class Attribute Attribute implements the association of an AttributeType or more generally an AttributeDescription with one or more AttributeValues. There are a wide variety of constructors available as a convenience to the application designer. 2.6.1 Constructors public Attribute(AttributeType type) Constructs an Attribute from an AttributeType. The resulting Attribute has no values. These may be assigned later via addValue or addValues. Expires 8/99 [Page 8] JAVA LDAP API February 1999 public Attribute(AttributeDescription desc) Constructs an Attribute from an AttributeDescription. The resulting Attribute has no values. These may be assigned later via addValue or addValues. public Attribute(AttributeType type, AttributeValue value) Constructs an Attribute from an AttributeType and a single AttributeValue. Additional values may be assigned later via addValue or addValues. public Attribute(AttributeType type, AttributeValue[] values) Constructs an Attribute from an AttributeType and an array AttributeValues. Additional values may be assigned later via addValue or addValues. public Attribute(AttributeDescription desc, AttributeValue[] values) Constructs an Attribute from an AttributeDescription and an array AttributeValues. Additional values may be assigned later via addValue or addValues. public Attribute(AttributeType type, java.util.Vector v) Constructs an Attribute from an AttributeType and a Vector of AttributeValues. Additional values may be assigned later via addValue or addValues. public Attribute(AttributeDescription desc, java.util.Vector v) Constructs an Attribute from an AttributeDescription and a Vector of AttributeValues. Additional values may be assigned later via addValue or addValues. public Attribute(java.lang.String desc, java.lang.String value) Constructs an Attribute from an AttributeType and a String representing a single attribute value. Additional values may be assigned later via addValue or addValues. public Attribute(java.lang.String desc, byte[] value) Constructs an Attribute from an AttributeType and a byte[] representing a single attribute value. Additional values may be assigned later via addValue or addValues. Expires 8/99 [Page 9] JAVA LDAP API February 1999 2.6.2 toString public java.lang.String toString() Returns a String listing the values of this Attribute in LDIF format. Useful for debugging or simple applications that need to display the contents of an Attribute. Returns: a String listing of the values 2.6.3 addValue public void addValue(java.lang.String val) Adds a single String value to the Attribute. Parameters: val - the String value to add 2.6.4 addValue public void addValue(byte[] val) Adds a single byte[] value to the Attribute. Parameters: val - the byte[] value to add 2.6.5 addValue public void addValue(AttributeValue val) Add a single AttributeValue to the Attribute. Parameters: val - the AttributeValue to add 2.6.6 addValues public void addValues(AttributeValue[] vals) Merges the array of AttributeValues with the values already associated with this Attribute. Parameters: vals - the array of AttributeValues to merge 2.6.7 size public int size() Returns the number of AttributeValues for this Attribute. Expires 8/99 [Page 10] JAVA LDAP API February 1999 2.6.8 getType public AttributeType getType() Returns the AttributeType of this Attribute 2.6.9 getDescription public AttributeDescription getDescription() Returns the AttributeDescription of this Attribute 2.6.10 getValues public AttributeValue[] getValues() Returns an array of the AttributeValues for this Attribute 2.6.11 getStringValues public java.lang.String[] getStringValues() Returns an array of Strings representing the values of this Attribute. The form of each of the strings depends on the syntax of the values for this Attribute. If the value was originally presented as a byte[] then a conversion is performed from the byte[] via UTF-8 to a string value; otherwise the AttributeValue was constructed from a String and no conversion is performed. Returns: the array of AttributeValues 2.6.12 getByteValues public byte[][] getByteValues() Returns a byte[] representing the values of this Attribute. The form of each byte[] depends on the syntax of the values for this Attribute. if a value was originally presented as a String then it is converted to a byte[] representation of the UTF-8 encoding of the string; otherwise, the original values are simply returned. Returns: the byte[] value. 2.7 Class org.ietf.ldap.AttributeDescription public class AttributeDescription extends AttributeType The AttributeDescription extends the AttributeType with any options associated with the coding of values of an Attribute. These descriptions are in accordance with RFC 2251 section 4.1.5. Accessors are provided so that subsets of options of a given description may be formed based on features of the description such as the occurrence of a Expires 8/99 [Page 11] JAVA LDAP API February 1999 given prefix, e.g., "lang-en". 2.7.1 Constructors public AttributeDescription(OID oid) Constructs an AttributeDescription from the given OID. The description has no name and no options. Parameters: oid - of the new attribute description. public AttributeDescription(java.lang.String desc) Constructs an AttributeDescription from a string using the syntax from RFC 2251 section 4.1.5. Parameters: desc - the attribute type and any options. public AttributeDescription(OID oid, java.lang.String name) Constructs an AttributeDescription from an (dotted numeric string) and a name. This constructor essentially builds a AttributeType that associates the name to the given OID with no options. Parameters: oid - the dotted numeric string for an OID. name - of attributes with the type oid. public AttributeDescription(OID oid, java.lang.String[] options) Constructs an AttributeDescription from an OID (dotted numeric string) and a list of options. There is no name associated with the given OID, so the type is known only via the oid. Parameters: oid - the dotted numeric string for an OID. options - list of options for this attribute description, public AttributeDescription(java.lang.String name, java.lang.String[] options) Constructs an AttributeDescription from a name and a list of options that further qualify the attribute type and its value. Parameters: name - of attributes with this type. options - list of options for this attribute description public AttributeDescription(OID oid, java.lang.String name, java.lang.String[] options) Expires 8/99 [Page 12] JAVA LDAP API February 1999 Constructs an AttributeDescription from an OID (dotted numeric string) a name and a list of options. Parameters: oid - the dotted numeric string for an OID name - of attributes with this type. options - list of options for this attribute description. 2.7.2 toDescriptions public static AttributeDescription[] toDescriptions(java.lang.String[] strings) Generates an array of AttributeDescriptions from a String[]. 2.7.3 toStrings public static java.lang.String[] toStrings(AttributeDescription[] atts) A utility that generates a list of String descriptions from a list of AttributeDescriptions. Parameters: atts - a list of AttributeDescriptions Returns: a list of corresponding string descriptions 2.7.4 toString public java.lang.String toString() Returns the full description in string form using the syntax of RFC 2251 section 4.1.5. 2.7.5 getType public AttributeType getType() Returns just the type portion of this attributes description. 2.7.6 getOptions public java.lang.String[] getOptions() Return a list of the options for this description. 2.7.7 includes public boolean includes(java.lang.String lang) Return true if at least one option starts with lang. This method may be used to test whether this description pertains to a given language by providing for example "lang-en". It could also be used to test whether Expires 8/99 [Page 13] JAVA LDAP API February 1999 the description describes an attribute value encoded as binary via "binary". The test is case insensitive. 2.7.8 includes public boolean includes(java.lang.String[] s) Returns true if every element of the given list of Strings is a prefix of at least one option of the description. The test is case insensitive. 2.7.9 getSubOptions public java.lang.String[] getSubOptions(java.lang.String lang) Returns all the options that start with lang. This essentially captures the idea that lang subsumes all of the returned options. For example, "lang-en" subsumes both "lang-en-US" and "lang-EN-gb". 2.7.10 isSubtype public boolean isSubtype(AttributeDescription other) Compares the options of this with the options of other and returns true if the options of other are a strict subset of the options of this. Parameters: other - is the candidate supertype of this. 2.7.11 isSubtypeEq public boolean isSubtypeEq(AttributeDescription other) Compares the options of this with the options of other and returns true if the options of other are a (possibly equal) subset of the this. Parameters: other - is the candidate super type of this. Returns: true if other's options are a subset of this.options. 2.7.12 addOption public void addOption(java.lang.String option) Adds a new option to the description ensuring that the options are in sorted order. This is the order that will be returned by a toString() or getOptions(). Parameters: option - to be added to the description. 2.7.13 addOptions Expires 8/99 [Page 14] JAVA LDAP API February 1999 public void addOptions(java.lang.String[] opts) Adds a list of options to the description ensuring that the options are in sorted order. This is the order that will be returned by a toString() or getOptions(). Parameters: opts - array of options to be added to the description. 2.8 Class org.ietf.ldap.AttributeSet public class AttributeSet implements java.lang.Cloneable An AttributeSet is simply a collection of Attributes. It provides a convenient way of manipulating a set of Attributes to be sent in a message or retrieved perhaps from an Entry. One notable use is to collect together all the Attributes from an Entry that have a common AttributeType but possibly differing AttributeDescriptions, such as different languages. This class provides methods for extracting a subset of a set that have a common type or description and supports the language subtyping rules in draft-ietf-ldapext-lang-01.txt. 2.8.1 Constructors public AttributeSet() public AttributeSet(Attribute[] a) 2.8.2 toString public java.lang.String toString() Returns a String representation conforming to LDIF for the elements of the set. 2.8.3 elementAt public Attribute elementAt(int i) 2.8.4 elements public java.util.Enumeration elements() Enumerates the attributes in the set. That is, nextElement() will return instances of Attribute. 2.8.5 size public int size() Returns: the number of Attributes in the set. 2.8.6 addElement Expires 8/99 [Page 15] JAVA LDAP API February 1999 public AttributeSet addElement(Attribute elem) Adds an Attribute to the set. No check is performed to verify that the added element is unique. Parameters: elem - the Attribute to add to the set. 2.8.7 getAttributes public AttributeSet getAttributes(AttributeType type) There can be many Attributes with the same AttributeType but different options hence different AttributeDescriptions. This method returns all of these Attributes. 2.8.8 getAttributes public AttributeSet getAttributes(AttributeDescription desc) Returns the subset of attributes that have at least as much detail as desc. 2.8.9 getAttributes public AttributeSet getAttributes(AttributeType type, java.lang.String optionPrefix) Returns the subset of attributes with the given type and an option at least as specific as optionPrefix. While intended for "lang-" options any options with a common prefix will do, e.g. "x-image", etc. 2.8.10 getAttributes public AttributeSet getAttributes(AttributeDescription desc, java.lang.String optionPrefix) Returns the subset of attributes that have at least as much detail as desc and an option at least as specific as optionPrefix. While intended for "lang-" options any options with a common prefix will do, e.g. "x- image", etc. 2.8.11 getAttributes public AttributeSet getAttributes(java.lang.String optionPrefix) Returns the subset of attributes that have an option at least as specific as optionPrefix. While motivated by "lang-" options, any options with a common prefix will do, e.g. "x-image", etc. 2.9 Class org.ietf.ldap.AttributeType Subclasses: Expires 8/99 [Page 16] JAVA LDAP API February 1999 AttributeDescription public class AttributeType extends SchemaElementId The AttributeType represents the OID and name(s) by which a given Attribute is known. If both a name and OID are present in an instance of Attribute then the instance can considered to assign the name to the OID. 2.9.1 Constructors public AttributeType(OID oid) public AttributeType(java.lang.String name) public AttributeType(OID oid, java.lang.String name) 2.9.2 equals public boolean equals(AttributeDescription desc) Tests whether given AttributeDescription is of this AttributeType. Returns: whether the description is of this type 2.9.3 toDescription public AttributeDescription toDescription() Converts an AttributeType to an AttributeDescription. 2.10 Class org.ietf.ldap.AttributeValueAssertion public class AttributeValueAssertion extends java.lang.Object The AttributeValueAssertion implements an assertion about the value of an attribute of the given description as specified in RFC 2251. If the "binary" option is present in attribute description, this signals to the server that the assertion is a binary encoding of the assertion value. See ByteArrayAssertion. For all the string-valued user attributes described in RFC 2252, the assertion value syntax is the same as the value syntax. Clients may use attribute values as assertion values in compare requests and search filters. Note however that the assertion syntax may be different from the value syntax for other attributes or for non-equality matching rules. These may have an assertion syntax which contains only part of the value. See section 20.2.1.8 of X.501 for examples. Expires 8/99 [Page 17] JAVA LDAP API February 1999 2.10.1 Constructors public AttributeValueAssertion(AttributeDescription desc, AssertionValue assertion) public AttributeValueAssertion(java.lang.String desc, java.lang.String assertion) public AttributeValueAssertion(java.lang.String desc, byte[] assertion) 2.10.2 toString public java.lang.String toString() 2.10.3 getType public AttributeType getType() Returns the AttributeType of this assertion. 2.10.4 getDescription public AttributeDescription getDescription() Returns the AttributeDescription of this assertion. 2.10.5 getAssertion public AssertionValue getAssertion() Returns the value asserted as an AssertionValue. 2.10.6 getStringAssertion public java.lang.String getStringAssertion() Returns a String representing the asserted value. The form of the String depends on the syntax of the asserted value for this AttributeValueAssertion. If the value was originally presented as a byte[] then it is converted to a String via a UTF-8 decoding of the string if possible; otherwise, the original value are simply returned. 2.10.7 getByteArrayAssertion public byte[] getByteArrayAssertion() Returns a byte[] representing the asserted value. The form of the byte[] depends on the syntax of the asserted value for this AttributeValueAssertion. If the value was originally presented as a String then it is converted to a byte[] representation of the UTF-8 encoding of the string; otherwise, the original value are simply Expires 8/99 [Page 18] JAVA LDAP API February 1999 returned. 2.11 Class org.ietf.ldap.AttributeValue public abstract class AttributeValue extends java.lang.Object The AttributeValue encapsulates the different possible representations such as String and byte[], for an attribute value. 2.11.1 make public static AttributeValue make(byte[] val) Returns an AttributeValue represented by the byte[]. Parameters: val - the byte[] representation 2.11.2 make public static AttributeValue make(java.lang.String val) Returns an AttributeValue represented by the String. Parameters: val - the String representation 2.11.3 size public abstract int size() 2.11.4 toString public abstract java.lang.String toString() Returns a String representation of the AttributeValue. If the value used to construct the AttributeValue was a byte[] then it is converted to a String via UTF-8. If the byte[] does not encode a String via UTF-8 then null is returned. Returns: the String representation of this AttributeValue. 2.11.5 isBinary public abstract boolean isBinary() Returns true if the AttributeValue must be encoded as binary in an LDIF representation. 2.11.6 toLDIFString public abstract java.lang.String toLDIFString() Expires 8/99 [Page 19] JAVA LDAP API February 1999 2.11.7 toBytes public abstract byte[] toBytes() Returns the byte[] representation of the AttributeValue. If the value used to construct the AttributeValue was a String then it is converted to a byte[] via UTF-8. 2.12 Class org.ietf.ldap.BasicControls public class BasicControls extends java.lang.Object implements Controls Provides the default implementation of the Controls interface. It is a collection of individual Control objects. 2.12.1 Constructors public BasicControls() public BasicControls(Control[] ca) Constructs an instance from the given array of Control objects. Primarily used when receiving a collection of Control objects in a message. public BasicControls(java.util.Vector cv) 2.12.2 size public int size() Return the number of Control objects in the collection 2.12.3 get public Control get(java.lang.String ctrlId) Return the Control with the corresponding control type OID in String form. 2.12.4 get public Control get(OID ctrlId) Return the Control with the corresponding control type OID 2.12.5 getAll public java.util.Enumeration getAll() Expires 8/99 [Page 20] JAVA LDAP API February 1999 Return an Enumeration of the Control objects in the collection. 2.12.6 toArray public Control[] toArray() Return an array of the Controls in the collection. 2.12.7 getIds public java.util.Enumeration getIds() Returns an Enumeration of the control type OIDs for the Controls in the collection. 2.12.8 put public Control put(Control ctrl) Add a Control to the collection. If there is a Control of the same type in the collection it is replaced by the given Control and the previous Control is returned as the result of the method; otherwise null is returned. 2.12.9 remove public Control remove(java.lang.String ctrlId) Removes the Control with the given control type OID represented as a String. The removed Control is returned as the result of the method. 2.12.10 remove public Control remove(OID ctrlId) Removes the Control with the given control type OID represented as a String. The removed Control is returned as the result of the method. 2.13 Class org.ietf.ldap.Continuation public class Continuation extends URLList A Continuation is a list of urls to other servers that should be contacted to continue a search. A Continuation is ONLY returned via an LDAP SearchResultReference, and is otherwise, the same as a URLList. It is useful whan an application is performing referral handling on its own. This distinguishes the case of a SearchResultDone with a referral that indicates that the contacted server was not able to locate the base entry of the search. 2.13.1 Constructors public Continuation(java.util.Vector urls) Expires 8/99 [Page 21] JAVA LDAP API February 1999 public Continuation(java.lang.String[] s) 2.13.2 toString public java.lang.String toString() Returns the String representation of the first url on the list of urls. 2.14 Class org.ietf.ldap.Control Subclasses: AttributeSizeLimitControl, ChainServerControl, ManageDsaITControl, MatchedValuesOnlyControl, NoChainingControl, NoCopyControl, SimplePagedControl, SortRequestControl, SortResponseControl, TriggerControl public abstract class Control extends java.lang.Object Control is an abstract class that is the base class for all the LDAP controls that can be sent to an LDAP server or received in a response from an LDAP server. A new controlType is implemented by extending Control with the fields that represent the controlValue for the Control, defining the static NAME and OID for the controlType, registering the Control, and defining the methods: controlValue controlValueString and any accessors appropriate to the controlValue components of the Control. 2.14.1 Constructors public Control(java.lang.String name, OID oid, boolean criticality) Constructs a Control with no controlValue for the specified OID with the given criticality. Parameters: oid - the type of the control criticality - true = operation should be discarded if server does not support this control public Control(java.lang.String name, OID oid) Constructs a non-critical ControlSeq with no controlValue for the specified OID. Parameters: oid - the id of the control 2.14.2 fromAsn Expires 8/99 [Page 22] JAVA LDAP API February 1999 public static Control fromAsn(java.lang.String controlType, boolean criticality, org.ietf.ldap.asn.AsnOctets controlValue) fromAsn uses the oid in the received control to locate the Class for corresponding controlType. The Class is instantiated via newInstance() then requested via its init method to initialize the instance with the received criticality and controlValue. 2.14.3 init public void init(boolean crit, org.ietf.ldap.asn.AsnOctets cv) Performs initialization of the criticality and controlValue fields of an instance built from ASN.1. This method typically needs to be overridden in the implementation of specific controls since the specific control is the locus of the information about how the control value is encoded. Parameters: criticality - the criticality encoded in the message controlValue - the OCTET STRING encoding of the controlValue 2.14.4 toAsn public org.ietf.ldap.apdu.ControlSeq toAsn() This method converts any Control to its corresponding ASN.1 SEQUENCE for writing on the wire. This method will typically be overridden in each specific Control's class to implement the control specific encoding of the controlValue for the specific control. This method is not intended to be called by users, rather it is called from the machinery that is responsible for de-serializing objects from the BER. Returns: the ControlSeq PDU component. 2.14.5 getControlName public java.lang.String getControlName() Return a local name (if any) for this type of Control. 2.14.6 getControlType public OID getControlType() Return the OID by which this type of Control is known to both clients and servers. Expires 8/99 [Page 23] JAVA LDAP API February 1999 2.14.7 sameType public boolean sameType(Control c) Returns true if the given Control has the same type as this Control. Parameters: c - the Control to test for type equality 2.14.8 getCriticality public boolean getCriticality() Return the current criticality for this Control. 2.14.9 toString public java.lang.String toString() Generate a String representation for this Control. 2.15 Class org.ietf.ldap.CramMD5SaslCredentials public class CramMD5SaslCredentials extends SaslCredentials CramMD5SaslCredentials implements the use of CRAM-MD5 in the simple authentication and security layer. The credentials are computed in accordance with RFCs 2095 and 2104. 2.15.1 Constructors public CramMD5SaslCredentials() Creates an instance that has null credentials which translates to absent credentials over protocol. An instance of this type is used to signal the start (or re-start) of a Sasl bind using the CRAM-MD5 mechanism. public CramMD5SaslCredentials (byte[] authzId, java.lang.String password, byte[] challenge) Creates credentials initialized from the give authorization id, password, and challenge. The credentials are computed in accordance with RFCs 2095 and 2104. Parameters: authzId - authorization id, may be null password - the secret information shared between the user and the server challenge - from the server public CramMD5SaslCredentials(byte[] authzId, Expires 8/99 [Page 24] JAVA LDAP API February 1999 byte[] password, byte[] challenge) Creates credentials initialized from the give authorization id, password, and challenge. The credentials are computed in accordance with RFCs 2095 and 2104. Parameters: authzId - authorization id, may be null password - the secret information shared between the user and the server challenge - from the server 2.15.2 getMethod public java.lang.String getMethod() Returns the SASL method name "CRAM-MD5" 2.16 Class org.ietf.ldap.DNAttributeTypeAndValue public class DNAttributeTypeAndValue extends java.lang.Object Instances of this class represent an attribute type and corresponding value as a component of an RDN. 2.16.1 Constructors public DNAttributeTypeAndValue(java.lang.String type, java.lang.String val) Construct an attributeTypeAndValue as one of possibly several values of an RDN from a given type and value. The value is assumed to not be escaped and escape processing will be applied. Parameters: type - of the attribute val - the unescaped value of the attribute. public DNAttributeTypeAndValue(java.lang.String type, byte[] val) Construct an attributeTypeAndValue as one of possibly several values of an RDN from a given type and value. The value is assumed to not be escaped and escape processing will be applied. Parameters: type - of the attribute val - the unescaped value of the attribute. 2.16.2 getType public AttributeType getType() Expires 8/99 [Page 25] JAVA LDAP API February 1999 Returns the AttributeType of this RDN component. 2.16.3 getValue public AttributeValue getValue() Returns the unescaped form of the value for this attributeTypeAndValue 2.16.4 toAttribute public Attribute toAttribute() Returns an Attribute consisting of the given AttributeType and the single given value. 2.16.5 toString public java.lang.String toString() Returns the attributeTypeAndValue as a String conforming to RFC 2253. The return value is suitable for use in the string representation of a distinguished name. 2.17 Class org.ietf.ldap.DN public class DN extends java.lang.Object This class manages the construction of distinguished names and access to their component parts. The syntax for a distinguished name may be found in RFC 2253 section 3, which discusses the UTF-8 string representation of distinguished names. A distinguished name is a sequence of relative distinguished names (RDN) each of which expresses one or more attribute type and value equalities, e.g. ("cn=Bill Jones"). An attribute type may also be presented as an OID (a dotted numeric string, e.g. 1.3.6.1.4.1.1466.0). 2.17.1 Constructors public DN() Constructs an empty DN public DN(java.lang.String dn) Constructs a DN representation of the distinguished name written in the parameter String. The string is presumed to conform to RFC 2253 section 3. 2.17.2 getLeaf public RDN getLeaf() Expires 8/99 [Page 26] JAVA LDAP API February 1999 Returns the leftmost RDN of this DN. If this is the root DN then an empty RDN is returned. 2.17.3 getParent public DN getParent() Returns the parent DN for this DN. If this is the root DN then the current instance is simply returned. 2.17.4 getRDNs public RDN[] getRDNs() Returns the list of RDNs for this DN. 2.17.5 toString public java.lang.String toString() Return a standard String representation for this distinguished name. 2.17.6 toURLstring public java.lang.String toURLstring() Return a URL encoded String representation for this distinguished name. 2.18 Class org.ietf.ldap.Entity Subclasses: Entry, URLList public class Entity extends java.lang.Object An Entity is either an Entry or a URLList. See EntityEnumeration and SearchResults. Essentially, an application that is performing referral following will expect an Entity as a search result. An application that relies on the SearchResults to perform referral following will expect only an Entry as a search result. 2.18.1 Constructors public Entity() 2.19 Class org.ietf.ldap.Entry Subclasses: RootDSEntry public class Entry extends Entity Expires 8/99 [Page 27] JAVA LDAP API February 1999 An Entry models the basic unit of an LDAP directory. 2.19.1 Constructors public Entry() public Entry(DN dn, AttributeSet attrs) 2.19.2 toString public java.lang.String toString() Returns a String representation of the Entry in accordance with LDIF syntax. 2.19.3 getDN public DN getDN() Returns the distinguished name of the Entry. 2.19.4 getAttributes public AttributeSet getAttributes() Returns an AttributeSet of all of the Attributes in the Entry. 2.19.5 getAttributes public AttributeSet getAttributes(AttributeType type) There can be many Attributes with the same AttributeType but different options hence different AttributeDescriptions. This method returns all of these Attributes. 2.19.6 getAttributes public AttributeSet getAttributes(AttributeDescription desc) Return the subset of attributes that are subtypes of desc 2.19.7 getAttributes public AttributeSet getAttributes(AttributeType type, java.lang.String lang) Return the subset of attributes of type, type and with at least one option in the description that has a prefix of lang. The test is case insensitive. 2.19.8 getAttributes public AttributeSet getAttributes(AttributeDescription desc, java.lang.String lang) Expires 8/99 [Page 28] JAVA LDAP API February 1999 Return the subset of attributes that are subtypes of desc with at least one option in the description that has a prefix of lang. The test is case insensitive. 2.19.9 getAttributes public AttributeSet getAttributes(java.lang.String lang) Return the subset of attributes that have at least one option with lang as a case insensitive prefix. 2.20 Class org.ietf.ldap.Enum Subclasses: AliasDeref, ModifyOp, Scope, SortResult public abstract class Enum extends java.lang.Object Enum is the base class for all enumerated types. An enumerated type has a fixed set of values. Each value has a (meaningful)name and and a code that is used in the ASN.1 representation for the value. Enumerated types are used in the api to support well typed use of LDAP. They are similar to the C API's constant definitions with the additional benefit that they are type checked where they occur. An enumerated type is defined by extending Enum and defining a private constructor that is invoked from within static constructors for each of the instances of the type. For example: public class Foo extends Enum { public static Foo bar = new Foo("bar", 1); public static Foo baz = new Foo("baz", 2); private Foo(String name, int code) { this.name = name; this.code = code; } defines an enumerated type Foo with values Foo.bar and Foo.baz. 2.20.1 toString public java.lang.String toString() Returns the name of the value. 2.20.2 toCode public int toCode() Returns the ASN.1 code assigned to the value. 2.21 Class org.ietf.ldap.ExternalSaslCredentials Expires 8/99 [Page 29] JAVA LDAP API February 1999 public class ExternalSaslCredentials extends SaslCredentials ExternalSaslCredentials are used to convey credentials between the SDK and underlying SSL or TLS security layers. 2.21.1 Constructors public ExternalSaslCredentials(java.lang.String authzId) 2.21.2 getMethod public java.lang.String getMethod() Returns the SASL method Stirng. 2.22 Class org.ietf.ldap.Filter public class Filter extends java.lang.Object Filter encapsulates the RFC 2254 compliant string expression for a filter and the internal FilterChoice structure used to write the ASN.1 encoding for the filter. 2.22.1 Constructors public Filter(java.lang.String filterExpr) throws ParseException Constructs a Filter with a string representing a filter as defined in RFC 2254. The representing field filterExpr is constructed from the FilterChoice object, which is in interpreted from the input filterExpr. Parameters: filterExpr - string which to parse and construct itself. Throws: ParseException - If there is an error parsing the filter expression string. public Filter(org.ietf.ldap.apdu.FilterChoice fc) Constructs a Filter from a FilterChoice object. Parameters: filterChoice - FilterChoice object from which to construct itself. 2.22.2 toString public java.lang.String toString() Returns a String representation of itself Expires 8/99 [Page 30] JAVA LDAP API February 1999 2.22.3 toURLstring public java.lang.String toURLstring() Returns a String representation of itself that is URL "safe". 2.22.4 internal public org.ietf.ldap.apdu.FilterChoice internal() Returns a FilterChoice representation of itself. 2.23 Class org.ietf.ldap.Interaction public class Interaction extends java.lang.Object An Interaction models the flow of messages for a single client/server interaction such as a modify or search. A request to getMessage will block the caller until there is a message available and request to putMessage places a message in the interaction. The Interaction supports completely asynchronous interaction between the using code and the connection(s) that support the interaction with the other end- point. 2.23.1 Constructors public Interaction(org.ietf.ldap.apdu.Connection con, int msgId) An Interaction is created by Connection or a subclass to represent the interaction between one or more connections and a user (client or server) for a single request/response instance, e.g., a modify or a search interaction between client and server. Due to referral handling there may be several connections involved with a single Interaction. 2.23.2 expect public void expect(int messageId) Informs the Interaction to expect messages with sequence number messageId. This is used to provide bookkeeping for the outstanding messsages on an Interaction. 2.23.3 close public void close(int messageId) Mark this Interaction as closed. I.e., there should be no more messages put into this Interaction. An Interaction may be closed because the last message in the interaction has been received or because the connection(s) over which the Interaction is occurring has been closed. This method is intended to be called by Connection or a subclass. Parameters: Expires 8/99 [Page 31] JAVA LDAP API February 1999 messageId - no longer expecting messages for this id - final response received 2.23.4 isClosed public boolean isClosed() Returns whether the interaction has been closed or not. An Interaction is closed when either the consumer is finished using it or when the connection(s) with which it is associated are closed. 2.23.5 getMessageId public int getMessageId() Returns the most recent messageId that was signalled via an expect(). 2.23.6 getMessage public Message getMessage() Get the next message in an interaction. The caller is blocked until either there is a message available or until all connections on which the interaction is participating have been closed. 2.23.7 putMessage public void putMessage(Message message) Puts a message into the interaction. Any threads waiting on the interaction are notified. It is erroneous to attempt to put a message into an interaction that is already closed. This method is intended to be called by Connection or a subclass. Parameters: message - the message to add to the interaction 2.24 Class org.ietf.ldap.LDAPURL public class LDAPURL extends java.lang.Object LDAPURL implements LDAP URLs as defined in RFC 2255. In addition to containing the host and port information, LDAP URL's allow search parameters to be encoded with the URL. The question mark (?) character is reserved as a delimiter for the search parameters. Other "unsafe" characters (as described in RFC 1738 section 2.2) must be encoded using the percent sign (%) escaping mechanism. 2.24.1 Constructors public LDAPURL() Constructs an empty, default URL Expires 8/99 [Page 32] JAVA LDAP API February 1999 public LDAPURL(java.lang.String url_str) bthrows ParseException Constructs an instance from a String representation of an LDAP URL. The String must conform to RFC 2255. Parameters: url_str - the String representing an LDAP URL 2.24.2 toString public java.lang.String toString() Returns: a String representation of itself that is URL "safe" according to RFC 2255 2.24.3 getScheme public java.lang.String getScheme() Returns: String representing the scheme of this URL, typically "ldap". 2.24.4 setHost public void setHost(java.lang.String host) Sets the host name to which this URL refers. Parameters: host - String representation of a host name 2.24.5 getHost public java.lang.String getHost() Returns: String representation the host name to which this URL refers. Local host name is default. 2.24.6 setPort public void setPort(int port) Sets the port number to which this URL refers. Parameters: port - int representation of a port number 2.24.7 getPort public int getPort() Returns: int representation of the port number to which this URL refers. LDAP port 389 is default. Expires 8/99 [Page 33] JAVA LDAP API February 1999 2.24.8 setDN public void setDN(DN dn) Sets the DN parameter of the search part of this LDAP URL. Parameters: dn - DN of base object in search 2.24.9 getDN public DN getDN() Returns: DN of base object in search part of this LDAP URL. 2.24.10 setAttributes public void setAttributes(AttributeDescription[] attributes) Sets the attributes parameter of the search part of this LDAP URL. Parameters: attributes - array of AttributeDescription objects which to return in the specified search 2.24.11 getAttributes public AttributeDescription[] getAttributes() Returns: array of AttributeDescription objects which are to be returned in the search specified in the LDAP URL. 2.24.12 setScope public void setScope(Scope scope) Sets the scope parameter of the search part of this LDAP URL. Parameters: scope - Scope of the search specified 2.24.13 getScope public Scope getScope() Returns: Scope of the search specified in this LDAP URL 2.24.14 setFilter public void setFilter(Filter filter) Sets the filter parameter of the search part of this LDAP URL. Expires 8/99 [Page 34] JAVA LDAP API February 1999 Parameters: filter - Filter of the search specified 2.24.15 getFilter public Filter getFilter() Returns: Filter of the search specified in this LDAP URL 2.24.16 setExtensions public void setExtensions(LDAPURLExtension[] extensions) Sets the extensions part of this LDAP URL. Parameters: extensions - array of LDAPURLExtension objects associated with this LDAP URL 2.24.17 getExtensions public LDAPURLExtension[] getExtensions() Returns: array of LDAPURLExtension objects specified by this LDAP URL 2.24.18 isSafe public static boolean isSafe(char c) Tests a character to determine whether or not it is "safe" according to RFC 2255. Parameters: c - char to test Returns: true if c is a "safe" character; false otherwise 2.24.19 isSafe public static boolean isSafe(java.lang.String s) Tests a String to determine whether or not it is "safe". A String is "safe" if it contains no "unsafe" characters. Parameters: s - String to test Returns: true if the s contains no "unsafe" characters; false otherwise 2.25 Class org.ietf.ldap.LDAPURLExtension public class LDAPURLExtension extends java.lang.Object Expires 8/99 [Page 35] JAVA LDAP API February 1999 LDAPURLExtension implements the extension construct for LDAP URLs as defined in RFC 2255. This construct provides the LDAP URL with an extensibility mechanism, allowing the capabilities of the URL to be extended in the future. Extensions are a simple comma-separated list of type=value pairs, where the =value portion MAY be omitted for options not requiring it. Each type=value pair is a separate extension. These LDAP URL extensions are not necessarily related to any of the LDAPv3 extension mechanisms. Extensions may be supported or unsupported by the client resolving the URL. An extension prefixed with a '!' character (ASCII 33) is critical. An extension not prefixed with a ' !' character is non-critical. If an extension is supported by the client, the client MUST obey the extension if the extension is critical. The client SHOULD obey supported extensions that are non-critical. If an extension is unsupported by the client, the client MUST NOT process the URL if the extension is critical. If an unsupported extension is non-critical, the client MUST ignore the extension. If a critical extension cannot be processed successfully by the client, the client MUST NOT process the URL. If a non-critical extension cannot be processed successfully by the client, the client SHOULD ignore the extension. Extension types prefixed by "X-" or "x-" are reserved for use in bilateral agreements between communicating parties. Other extension types MUST be defined in this document, or in other standards-track documents. 2.25.1 Constructors public LDAPURLExtension(java.lang.String extension_string) Constructs an instance from the specified parameters. Parameters: extension_string - String object assumed to consist of an oid, and optionally an equal sign followed by a value, prepended by an exclamation point if this extension is critical. public LDAPURLExtension(OID type, java.lang.String value, boolean critical) Constructs an instance from specified parameters. Parameters: type - oid of the extension value - String representing the extension value critical - true if this extension is critical 2.25.2 toURLstring public java.lang.String toURLstring() Returns: a String representation of itself which it LDAP URL "safe" as defined in RFC 2255 Expires 8/99 [Page 36] JAVA LDAP API February 1999 2.25.3 setDescription public void setDescription(OID type) Sets the OID of this extension Parameters: type - OID of the attribute 2.25.4 getDescription public OID getDescription() Returns: OID or this extension 2.25.5 setValue public void setValue(java.lang.String value) Sets the value of this extension Parameters: value - value of the extension 2.25.6 getValue public java.lang.String getValue() Returns: String representation of the value of this extension 2.25.7 setCriticality public void setCriticality(boolean critical) Sets the criticality of this extension Parameters: critical - true if this extension is critical 2.25.8 getCriticality public boolean getCriticality() Returns: true if this extension is critical 2.26 Class org.ietf.ldap.MatchingRuleId public class MatchingRuleId extends SchemaElementId The MatchingRuleId represents the OID and/or name by which a given MatchingRule is known. If both a name and OID are present in an instance of MatchingRuleId then the instance can considered to assign the name to the OID in the context of a specific type of server. Expires 8/99 [Page 37] JAVA LDAP API February 1999 2.26.1 Constructors public MatchingRuleId(OID oid) public MatchingRuleId(java.lang.String name) public MatchingRuleId(OID oid, java.lang.String name) 2.27 Class org.ietf.ldap.Message Subclasses: Response, SearchEntry, SearchReference public class Message extends java.lang.Object A Message is either an LDAP request or a result. It has a messageId and optional Controls. Any other fields are defined in subclasses according to the type from RFC 2251. Messages are defined completely in terms of types internal to the api and are independent of the coding in ASN.1. This allows a clean separation between the functions of encoding/ decoding ASN.1 and the application oriented functions of the abstract LDAP Message types. 2.27.1 Constructors public Message() 2.27.2 setMessageId public void setMessageId(int messageId) Sets the messageId. This is typically used in the implementation of connection objects and should not be of interest to the api user. Parameters: messageId - the message sequence number for this message 2.27.3 getMessageId public int getMessageId() Returns the message sequence number for this message. 2.27.4 setControls public void setControls(Control[] ca) Sets the controls of this message. Normally only used in the implementation of connection objects. This method appears here due to the order in which ASN.1 objects are decoded and the desire to construct message specific classes on-the-fly. Expires 8/99 [Page 38] JAVA LDAP API February 1999 Parameters: controls - the Control[] for this message 2.27.5 getControls public Controls getControls() Returns the Controls for this message or null if they are not present. 2.28 Class org.ietf.ldap.Modification public class Modification extends java.lang.Object A Modification is an operation, e.g. ADD or DELETE, and an Attribute that will be added or deleted from some entry. 2.28.1 Constructors public Modification(ModifyOp op, Attribute attribute) Constructs an Modification from the given operation and attribute. Parameters: op - the operation set - the attribute 2.28.2 setToModifications public static Modification[] setToModifications(ModifyOp op, AttributeSet set) Accepts an operation and a set of Attributes and returns an array of Modifications formed by associating the operation with each of the attributes in the set. Parameters: op - the operation set - the set of attributes Returns: the array of Modifications 2.28.3 getOp public ModifyOp getOp() Return the operation of the Modification. 2.28.4 setOp public void setOp(ModifyOp op) Sets the operation to be performed. Expires 8/99 [Page 39] JAVA LDAP API February 1999 Parameters: ModifyOp - specifying operation for the modification 2.28.5 getAttribute public Attribute getAttribute() Return the attribute to be modified. 2.29 Class org.ietf.ldap.ModifyOp public final class ModifyOp extends Enum ModifyOp is an enumerated type consisting of three constant values: ADD, DELETE, and REPLACE that correspond to the operations that may be requested of an LDAP directory on an attribute of an entry. 2.29.1 Fields public static final ModifyOp ADD public static final ModifyOp DELETE public static final ModifyOp REPLACE 2.29.2 toModifyOp public static ModifyOp toModifyOp(int code) Used by ASN.1 decode routines to obtain the Scope constant that corresponds to an ASN.1 value. Parameters: code - the ASN.1 value to map to a ModifyOp Returns: the ModifyOp corresponding to code or null 2.29.3 toName public static java.lang.String toName(int code) 2.30 Class org.ietf.ldap.NullSaslCredentials public class NullSaslCredentials extends SaslCredentials NullSaslCredentials are used to abort a Sasl bind in progress. The application may then initiate a new Sasl bind sequence with the same or different mechanism. 2.30.1 Constructors public NullSaslCredentials() Expires 8/99 [Page 40] JAVA LDAP API February 1999 2.30.2 getMethod public java.lang.String getMethod() Returns the SASL method name"NULL". 2.31 Class org.ietf.ldap.OID public class OID extends java.lang.Object The OID represents the globally unique object identifier for some LDAP element such as an objectClass or attributeType. 2.31.1 Constructors public OID(java.lang.String oid) 2.31.2 equals public boolean equals(OID other) Returns true if both OIDs are the same, false otherwise. 2.31.3 equals public boolean equals(java.lang.String other) Returns true if the given string represents the same OID. 2.31.4 toString public java.lang.String toString() Returns the conventional dotted numeric string representation of the OID. 2.32 Class org.ietf.ldap.RDN public class RDN extends java.lang.Object RDN represents a relative distinguished name as specified in RFC 2253 where its syntax is given as a name-component. The components of an RDN may be obtained via toAttributes() which will return a list of Attributes representing each of the attributeTypeAndValues that comprise the RDN. 2.32.1 Constructors public RDN(java.lang.String spec) Constructs an RDN from a String, spec,. Expires 8/99 [Page 41] JAVA LDAP API February 1999 Parameters: spec - the String representation of the RDN 2.32.2 getATAVs public DNAttributeTypeAndValue[] getATAVs() Returns an array of the attribute type and value objects that comprise the components of this RDN 2.32.3 toAttributes public Attribute[] toAttributes() Returns a list of Attributes that represent the attributeTypeAndValues of this RDN. 2.32.4 getTypeAndValues public java.lang.String[] getTypeAndValues() Returns a list of Strings of the form "=". 2.32.5 toString public java.lang.String toString() Returns a String representing this RDN according to the syntax in RFC 2253 section 3. 2.33 Class org.ietf.ldap.Referral public class Referral extends URLList A Referral is a list of urls to other servers that should be contacted to perform some operation, such as a search. A Referral is returned in via an LDAP Result with a result code of Referral. 2.33.1 Constructors public Referral(java.util.Vector urls) public Referral(java.lang.String[] s) 2.33.2 toString public java.lang.String toString() Returns a string representation of the list of URLs suitable for use in LDIF. 2.34 Class org.ietf.ldap.RootDSEntry Expires 8/99 [Page 42] JAVA LDAP API February 1999 public class RootDSEntry extends Entry RootDSEntry subclasses Entry for accessing server information contained in the root DS entry of a directory. 2.34.1 Constructors public RootDSEntry(java.lang.String host, int port) throws LDAPException Constructs an instance from a host and port of an LDAP server from which to retrieve the root DS entry. Parameters: host - Sting representing the host name of an LDAP server port - int representing the port number of an LDAP server public RootDSEntry(ClientConnection connection) throws LDAPException Constructs an instance from a connection already established to an LDAP server from which to retrieve the root DS entry. Parameters: connection - ClientConnection object representing a communication medium to an LDAP server public RootDSEntry(DirectoryClient client) throws LDAPException Constructs a RootDSEntry instance from the given client. 2.34.2 getDSEType public java.lang.String getDSEType() Returns: String representing the type of the DSE, e.g. "(root)". 2.34.3 getNamingContexts public DN[] getNamingContexts() Returns: an array of DNs representing naming contexts held in the server. Naming contexts are defined in section 17 of X.501 2.34.4 getServerName public DN getServerName() Returns: a DN representing the name of the server 2.34.5 getSupportedVersions Expires 8/99 [Page 43] JAVA LDAP API February 1999 public int[] getSupportedVersions() Returns: an array of ints representing LDAP versions implemented by the server 2.34.6 getAccessControlScheme public OID getAccessControlScheme() Returns: an OID representing the control which dictates access rights for users of this directory 2.34.7 getCurrentTime public java.lang.String getCurrentTime() Returns: a String representing the current time kept by the server 2.34.8 getSubSchemaEntry public DN getSubSchemaEntry() Returns: a DN representing the distinguished name of the subschema entry (or subentry) which controls the schema for this entry. 2.34.9 getSupportedSaslMechanisms public java.lang.String[] getSupportedSaslMechanisms() Returns: an array of Strings representing a list of supported SASL security features 2.34.10 getSupportedControls public OID[] getSupportedControls() Returns: an array of OIDs representing a list of controls supported by the server 2.34.11 getChangeLog public DN getChangeLog() Returns: a DN representing the distinguished name of the changelog directory tree. 2.34.12 getOgSupportedProfile public OID[] getOgSupportedProfile() Returns: an array of OIDs for the supported profiles. 2.35 Class org.ietf.ldap.SaslCredentials Expires 8/99 [Page 44] JAVA LDAP API February 1999 Subclasses: CramMD5SaslCredentials, ExternalSaslCredentials, NullSaslCredentials public abstract class SaslCredentials extends java.lang.Object SaslCredentials is an abstract class that is the root of all the classes that implement various simple authentication and security layer mechanisms. Implementing a new mechanism is done by subclassing SaslCredentials. It is necessary in each subclass to declare the method string as a static and to override the getMethod() accessor in subclass. 2.35.1 Constructors public SaslCredentials() public SaslCredentials(byte[] b) 2.35.2 getMethod public java.lang.String getMethod() Returns the method name for a SaslCredentials. This method is overriden in each subclass. 2.35.3 toBytes public byte[] toBytes() Returns a byte[] representing the credential value to be sent via protocol or that was received over protocol. 2.36 Class org.ietf.ldap.SchemaElementId Subclasses: AttributeType, MatchingRuleId, ObjectClassId, SchemaDescriptionId, SyntaxId public class SchemaElementId extends java.lang.Object The SchemaElementId represents the OID and name(s) by which a given schema element is known. If both a name and OID are present in an instance then the instance can considered to assign the name to the OID. 2.36.1 Constructors public SchemaElementId(OID oid) public SchemaElementId(java.lang.String name) Expires 8/99 [Page 45] JAVA LDAP API February 1999 public SchemaElementId(OID oid, java.lang.String name) 2.36.2 getOid public OID getOid() Return the OID if any associated with this SchemaElementId 2.36.3 setOid public void setOid(OID oid) Establish the OID for this SchemaElementID. 2.36.4 getName public java.lang.String getName() Return the name if any associated with this SchemaElementId. 2.36.5 setName public void setName(java.lang.String name) Set the name of this SchemaElementId. 2.36.6 equals public boolean equals(SchemaElementId other) Compares two SchemaElementIds. If both have an OID then the values must be identical. On the other hand, if one or both have null OIDs then the names must match. 2.36.7 toString public java.lang.String toString() If a name is available it is returned as the string representation for this id, else the associated OID in string form is returned. 2.36.8 toOidString public java.lang.String toOidString() Return the string representation of the associated OID or null if there is no OID associated. 2.37 Class org.ietf.ldap.Scope public final class Scope extends Enum Expires 8/99 [Page 46] JAVA LDAP API February 1999 Defines the constants that represent the three different scopes for a LDAP search. Each constant has a name and code that represents its value in the LDAP ASN.1 definition. An application designer need only use toName and the static constants of this class: Scope.BASE, Scope.ONELEVEL, and SCOPE.SUBTREE. 2.37.1 Fields public static final Scope BASE Limits a search to the Entry that named by the and that matches the Filter. public static final Scope ONELEVEL Limits the search to the Entry named by the DN and that entries children. public static final Scope SUBTREE Limits the search to the sub-tree rooted at the Entry named by the DN. 2.37.2 toScope public static Scope toScope(int code) Used by ASN.1 decode routines to obtain the Scope constant that corresponds to an ASN.1 value. Parameters: code - the ASN.1 value to map to a Scope Returns: the Scope corresponding to code or null 2.37.3 toName public static java.lang.String toName(int code) Returns the String name for an ASN.1 value. Parameters: code - ASN.1 value to map to a name 2.38 Class org.ietf.ldap.SDK public class SDK SDK defines constants related to an implementation of the LDAP API. 2.38.1 Fields public static final java.lang.String version Defines the version string of the interface instance. Expires 8/99 [Page 47] JAVA LDAP API February 1999 public static final java.lang.String product Defines the product or vendor string. public static final java.lang.String release Defines the vendor dependent release identification. 2.39 Class org.ietf.ldap.URLList Subclasses: Continuation, Referral public class URLList extends Entity A Referral is a list of urls to other servers that should be contacted to perform some operation, such as a search. 2.39.1 Constructors public URLList(java.util.Vector urls) public URLList(java.lang.String[] s) 2.39.2 getAll public java.lang.String[] getAll() Returns an array of the URL strings in the URLList. 2.39.3 getURLs public java.util.Vector getURLs() Returns a Vector of the URLs. 2.40 Class org.ietf.ldap.HopLimitException public class HopLimitException extends InterfaceException Thrown when an interface specific time limit is exceeded. 2.40.1 Constructors public HopLimitException() public HopLimitException(java.lang.String s) 2.40.2 Class org.ietf.ldap.InterfaceException Subclasses: Expires 8/99 [Page 48] JAVA LDAP API February 1999 HopLimitException, InterfaceTimeLimitException, LDAPURLExtensionNotSupportedException, ParseException, ReferralException public class InterfaceException extends LDAPException An exception thrown when an error occurs specific to the API interface as opposed to an LDAPException related to the protocol. 2.40.3 Constructors public InterfaceException() public InterfaceException(java.lang.String s) 2.41 Class org.ietf.ldap.InterfaceTimeLimitException public class InterfaceTimeLimitException extends InterfaceException Thrown when an interface specific time limit is exceeded. 2.41.1 Constructors public InterfaceTimeLimitException() public InterfaceTimeLimitException(java.lang.String s) 2.42 Class org.ietf.ldap.LDAPException Subclasses: InterfaceException, ProtocolException public class LDAPException extends java.lang.Exception A general purpose exception to be thrown by LDAP operations. 2.42.1 Constructors public LDAPException() public LDAPException(java.lang.String s) public LDAPException(java.lang.Exception e) 2.42.2 getMatchedDN public DN getMatchedDN() Returns the DN related to the LDAPException or null if there is no associated DN. Expires 8/99 [Page 49] JAVA LDAP API February 1999 2.43 Class org.ietf.ldap.ParseException public class ParseException extends InterfaceException ParseException is thrown for errors in the well-formedness of RFC 2254 filter specifications and DNs. Since the ParseException only occurs as a result of processing local to the API, it is an instance of InterfaceException. 2.43.1 Constructors public ParseException() public ParseException(java.lang.String s) 2.44 Class org.ietf.ldap.ProtocolException Subclasses: AdministrationLimitExceededException, AffectsMultipleDSAsException, AttributeOrValueExistsException, AuthenticationMethodNotSupportedException, BusyException, ConfidentialityRequiredException, ConstraintViolationException, DisconnectionException, EntryAlreadyExistsException, InappropriateAuthenticationException, InappropriateMatchingException, InsufficientAccessRightsException, InvalidAttributeSyntaxException, InvalidCredentialsException, LoopDetectException, MatchedDNException, NamingViolationException, NoSuchAttributeException, NotAllowedOnNonLeafException, NotAllowedOnRDNException, ObjectClassModificationsProhibitedException, ObjectClassViolationException, OperationsErrorException, OtherException, ProtocolErrorException, SizeLimitExceededException, StrongAuthenticationRequiredException, TimeLimitExceededException, UnavailableCriticalExtensionException, UnavailableException, UndefinedAttributeTypeException, UnwillingToPerformException public class ProtocolException extends LDAPException An exception thrown when an error occurs specific to the API protocol. 2.44.1 Constructors public ProtocolException() public ProtocolException(java.lang.String s) 3. Package org.ietf.ldap.client 3.0.1 Description Expires 8/99 [Page 50] JAVA LDAP API February 1999 Provides classes that model LDAP protocol components of that are particularly relevant to client-side applications. The principal class is DirectoryClient. This class provides synchronous/blocking access to a directory. The ClientConnection together with the Interaction class models the basic asynchronous access to a directory. SearchResults implements the EntityEnumeration allowing an application to iterate over a collection of Entries and (optionally) SearchReferences. 3.1 Interface org.ietf.ldap.client.Binder public abstract interface Binder This interface defines a single method that is used to perform a bind request (sequence) via a ClientConnection. A class implementing this interface, see DefaultBinder, will implement a use of the bind request that is appropriate for some server or class of servers. Typically a Binder will be produced by a BinderFactory, see DefaultBinderFactory, during implicit referral handling. The Binder is given access to the connection over which the bind is to be performed. 3.1.1 bind public BindResponse bind(ClientConnection conn) throws LDAPException Returns the final response to the bind. In the event that the bind is terminated in error then an exception is thrown. Note that if a SASL bind is used there may be many steps and only the final response will be returned. Parameters: conn - the connection to bind to Returns: the final response to the bind Throws: LDAPException - in the event of a failure during the bind 3.2 Interface org.ietf.ldap.client.BinderFactory public abstract interface BinderFactory This interface specifies a single method that will return a Binder corresponding to the the given host and port. A BinderFactory may use a authentication database, display a dialog to the user, or any other method that is appropriate for a given application, in order to generate an instance of a class that will be able to complete the bind operation for a given ClientConnection. 3.2.1 getBinder Expires 8/99 [Page 51] JAVA LDAP API February 1999 public Binder getBinder(String host, int port) throws LDAPException Returns a Binder suitable for performing a bind to the given host and port. Parameters: host - the name of the LDAP server host port - on which the server resides Throws: LDAPException - in the event of a failure during the bind. 3.3 Interface org.ietf.ldap.client.PageHandler public abstract interface PageHandler Provides the interface for handlers supplied by the application to be called when a SearchDone is received with a SimplePagedControl in effect. A PageHandler is established via SearchSpec.setPageHandler(PageHandler) on either the SearchSpec passed in the DirectoryClient.search or the default SearchSpec associated with a DirectoryClient or the SearchSpec on an active SearchResults If a search is performed with a non-zero page size, i.e., with a SimplePagedControl, then if the SearchSpec.pageHandler() is null then the SearchResults fetched pages implicitly until the search is finally done. 3.3.1 endOfPage public boolean endOfPage(SearchSpec spec, ClientConnection conn, Interaction x) throws LDAPException Should return true if the search is DONE else return false if more results should be anticipated. Parameters: spec - the SearchSpec in effect conn - the ClientConnection over which the last page was received x - the Interaction that is to be used in further requests Returns: true if the search is considered DONE else false 3.4 Class org.ietf.ldap.client.AddResponse public class AddResponse extends Response AddResponse implements the response to an LAP add request. There is no Expires 8/99 [Page 52] JAVA LDAP API February 1999 specific information provided. See Response. 3.4.1 Constructors public AddResponse(LDAPException ex, Referral ref) 3.5 Class org.ietf.ldap.client.BindResponse public class BindResponse extends Response BindResponse implements the response to an LDAP bind request. The specific information provided is the in-progress status of the bind and the SASL credentials (if any) from the server. 3.5.1 Constructors BindResponse public BindResponse(LDAPException ex, Referral ref, boolean b, byte[] creds) 3.5.2 isInProgress public boolean isInProgress() Returns true if the server reports SASL bind in-progress. 3.5.3 getServerCredentials public byte[] getServerCredentials() Returns any SASLCredentials that the server sent in the response. to a bind request. 3.6 Class org.ietf.ldap.client.ClientConnection public class ClientConnection extends org.ietf.ldap.apdu.Connection A ClientConnection supports asynchronous interaction with an LDAP server. Classes such as DirectoryClient and SearchResults may use a ClientConnection. Through a ClientConnection, a user may issue the various requests specified in RFC 2251: bind, unbind, search, modify, modify dn, compare, abandon, operations in addition to making extended requests. Each of the request methods returns an Interaction on which the user will receive any responses to the requested LDAP operation. A ClientConnection runs a Thread when instantiated. This thread listens for messages arriving from the server to which the ClientConnection is Expires 8/99 [Page 53] JAVA LDAP API February 1999 connected. When a message is received it is passed to the appropriate interaction from which it may be retrieved for application processing. All LDAP operations accept an interaction on which any messages received in response to the operation request will be placed. In this way a single interaction may be associated with many outstanding requests distributed across multiple ClientConnections. There is no ambiguity in responses from different servers on a single interaction since all messages over the life of the API instance are assigned a unique message id. If the interaction argument is null then the ClientConnection will create one to be used for responses to the given request. In all cases the request method returns the interaction on which the response(s) will be delivered. All operations except for connect accept a Controls to specify any Controls that may be meaningful for the operation on the connected server. If no Controls are to be sent then null is used to signal their absence. 3.6.1 Constructors public ClientConnection(String host, int port) throws LDAPException Establishes a connection to an LDAP server at the given host on the specified port. Parameters: host - to contact. port - the server is listening on. 3.6.2 bind public Interaction bind(int version, DN dn, String password, Interaction x) throws LDAPException Binds to the server using simple authentication. Parameters: version - integer representing bind version dn - distinguished name of of manager password - password of manager Returns: the Interaction on which the response will be returned Throws: LDAPException - a generic exception 3.6.3 bind Expires 8/99 [Page 54] JAVA LDAP API February 1999 public Interaction bind(int version, DN dn, byte[] password, Interaction x) throws LDAPException Binds to the server using simple authentication, the password is an arbitrary binary value. Parameters: version - integer representing bind version dn - distinguished name of of manager password - password of manager Returns: the Interaction on which the response will be returned Throws: LDAPException - a generic exception 3.6.4 bind public Interaction bind(int version, DN dn, SaslCredentials sasl, Controls controls, Interaction x) throws LDAPException Binds to the server using SASL authentication and controls. Parameters: version - integer representing bind version dn - distinguished name of of manager control - array of controls to send to server sasl - SASL credentials of manager Returns: the Interaction on which the response will be returned Throws: LDAPException - a generic exception 3.6.5 close public void close() Remove this connection from the table of active connections to servers and then call close on Connection. 3.6.6 unbind public void unbind() throws LDAPException Expires 8/99 [Page 55] JAVA LDAP API February 1999 Unbinds from the server. Throws: LDAPException - a generic exception 3.6.7 search public Interaction search(SearchSpec spec, Interaction x) throws LDAPException Requests a search. Returns: the Interaction on which the response will be returned Throws: LDAPException - a generic exception 3.6.8 search public Interaction search(DN base, Scope scope, AliasDeref deref, int size_limit, int time_limit, boolean types_only, Filter filter, AttributeDescription[] atts, Controls controls, Interaction x) throws LDAPException Requests a search. Parameters: base - place in LDAP tree to start searching scope - Scope.BASE, Scope.ONELEVEL, Scope.SUBTREE deref_aliases - AliasDeref.NEVER, AliasDeref.SEARCHING, AliasDeref.FINDING, AliasDeref.ALWAYS size_limit - maximum number of entries to be returned, or 0 if unlimited time_limit - maximum number of seconds the server should devote to the search, or 0 if unlimited types_only - true = return attributes only filter - search criteria to use atts - array of attributes to return or null control - array of controls to send to server or null x - the Interaction to use or null Returns: the Interaction on which the response will be returned Throws: LDAPException - a generic exception Expires 8/99 [Page 56] JAVA LDAP API February 1999 3.6.9 modify public Interaction modify(DN base, Modification[] mods, Controls controls, Interaction x) throws LDAPException Requests the modification of an entry. Parameters: base - place in LDAP tree to modify mods - array of modifications to be made control - array of controls to send to server x - the Interaction to use or null Returns: the Interaction on which the response will be returned Throws: LDAPException - a generic exception 3.6.10 add public Interaction add(DN entry, AttributeSet attrs, Controls controls, Interaction x) throws LDAPException An entry is added to the directory with the given distinguished name and Attributes. Optional controls may be supplied. Parameters: dn - of the entry to be added attrs - set of attributes to add under the given distinguished name controls - array of controls to send to server, or null x - the Interaction to use or null Returns: the Interaction on which the response will be returned Throws: LDAPException - a generic exception 3.6.11 delete public Interaction delete(DN entry, Controls controls, Interaction x) throws LDAPException Requests a delete. Parameters: Expires 8/99 [Page 57] JAVA LDAP API February 1999 entry - to delete control - list of controls to send or null x - the Interaction to use or null Returns: the Interaction on which the response will be returned Throws: LDAPException - a generic exception 3.6.12 modifyDN public Interaction modifyDN(DN entry, RDN new_rdn, boolean delete_old, DN new_superior, Controls controls, Interaction x) throws LDAPException Requests the renaming of an entry or sub-tree or the movement of an entire sub-tree. Parameters: base - location in the DIT to modify newRDN - new relative DN delete_old - if true delete the old RDN values new_superior - new parent for entry control - array of controls to send to server x - the Interaction to use or null Returns: the Interaction on which the response will be returned Throws: LDAPException - a generic exception 3.6.13 compare public Interaction compare(DN entry, AttributeValueAssertion ava, Controls controls, Interaction x) throws LDAPException Requests a comparison of an assertion with an entry in the directory. Parameters: entry - DN of entry to compare ava - assertion on attribute value to compare control - array of controls to send to server x - the Interaction to use or null Returns: the Interaction on which the response will be returned Throws: Expires 8/99 [Page 58] JAVA LDAP API February 1999 LDAPException - a generic exception 3.6.14 abandon public void abandon(int message_id, Controls controls) throws LDAPException Requests that a specific operation be abandoned. The message_id may be retrieved via Interaction.getMessageId() on the interaction associated with the request. In the event that the interaction is shared across multiple outstanding requests, it is appropriate for the application to use Interaction.getMostRecentId() when the request is sent and to manage the messageIds itself for potential future abandonment. Parameters: message_id - of the operation to abandon. control - array of controls to send to server Throws: LDAPException - a generic exception 3.6.15 extendedRequest public Interaction extendedRequest(OID name, byte[] value, Controls controls, Interaction x) throws LDAPException Makes an extended request. Parameters: name - oid of the request value - of the request control - array of controls to send to server x - the Interaction to use or null Returns: the Interaction on which the response will be returned Throws: LDAPException - a generic exception 3.6.16 issueExtended public Interaction issueExtended(org.ietf.ldap.apdu.ExtendedRequest exReq, Controls controls, Interaction x) throws LDAPException 3.7 Class org.ietf.ldap.client.CompareResponse public class CompareResponse Expires 8/99 [Page 59] JAVA LDAP API February 1999 extends Response CompareResponse returns the status of an LDAP compare request. 3.7.1 Constructors public CompareResponse(LDAPException ex, Referral ref, boolean success) 3.7.2 isTrue public boolean isTrue() Returns the status of the compare. Returns: true if the compare suceeded; otherwise false 3.8 Class org.ietf.ldap.client.DefaultBinder public class DefaultBinder implements Binder This Binder simply binds anonymously to the given ClientConnection. 3.8.1 Constructors public DefaultBinder() 3.8.2 bind public BindResponse bind(ClientConnection conn) throws LDAPException Returns the BindResponse resulting from an anonymous bind over the given ClientConnection. The response should be a successful response otherwise an exception will have been thrown. Parameters: conn - the connection to bind to Returns: the response to the bind 3.9 Class org.ietf.ldap.client.DefaultBinderFactory public class DefaultBinderFactory implements BinderFactory This BinderFactory returns a Binder that performs an anonymous bind on any connection. 3.9.1 Constructors Expires 8/99 [Page 60] JAVA LDAP API February 1999 public DefaultBinderFactory() 3.9.2 getBinder public Binder getBinder(String host, int port) throws LDAPException Returns a simple Binder, see DefaultBinder, that performs an anonymous bind on any ClientConnection. Parameters: host - ignored port - ignored Returns: instance of DefaultBinder Throws: LDAPException - never thrown 3.10 Class org.ietf.ldap.client.DelResponse public class DelResponse extends Response DelResponse implements the response object that is sent as a result of an LDAP delete request. There is no specific information for this response, see Response. 3.10.1 Constructors DelResponse public DelResponse(LDAPException ex, Referral ref) 3.11 Class org.ietf.ldap.client.DirectoryClient public class DirectoryClient extends V2DirectoryClient Provides a simple synchronous or blocking interface to an LDAP Directory. Through a DirectoryClient, a user can issue the various requests specified in RFC 2251: bind, unbind, search, modify, modify dn, compare, add, del, abandon in addition to making extended requests. Expires 8/99 [Page 61] JAVA LDAP API February 1999 All operations except for connect have a variant that accepts a Controls to specify any Control(s) that may be meaningful for the operation on the connected server. See Client and WatchChange for sample code that uses this object. 3.11.1 Constructors public DirectoryClient(String host, int port) throws LDAPException public DirectoryClient(ClientConnection con) Given a previously established ClientConnection a DirectoryClient is constructed that will operate over the connection. 3.11.2 getProtocolVersion public int getProtocolVersion() Returns the protocol version used: 3. 3.11.3 getHost public String getHost() Returns: the host to which the Connection is connected 3.11.4 getPort public int getPort() Returns: the port that was contacted to establish the connection 3.11.5 getClientConnection public ClientConnection getClientConnection() Returns the underlying ClientConnection. 3.11.6 setBinderFactory public void setBinderFactory(BinderFactory bf) Allows the application to establish the BinderFactory that will be used to generate Binders during referral following Parameters: bf - the new BinderFactory. 3.11.7 getBinderFactory public BinderFactory getBinderFactory() Expires 8/99 [Page 62] JAVA LDAP API February 1999 Returns the current BinderFactory. 3.11.8 isReferring public boolean isReferring() Return whether referrals are implicitly followed or not. 3.11.9 setReferring public boolean setReferring(boolean referring) Set whether to follow referrals implicitly or not. Returns: the previous state of referral following 3.11.10 isReturnReferrals public boolean isReturnReferrals() Return true if referrals are to be returned when not implicitly following referrals. 3.11.11 setReturnReferrals public boolean setReturnReferrals(boolean returning) Set whether to return referrals or not. Returns: previous state of returning referrals. 3.11.12 performReferral public Response performReferral(Message msg) throws ReferralException, ProtocolException Handles implicit referral processing if any for an LDAP response. Parameters: msg - the response, possibly a referral 3.11.13 bind public BindResponse bind(DN dn, SaslCredentials sasl) throws LDAPException Binds to the server using SASL authentication. Parameters: dn - of manager sasl - credentials of manager Throws: Expires 8/99 [Page 63] JAVA LDAP API February 1999 LDAPException - in the event of failure of the bind 3.11.14 bind public BindResponse bind(DN dn, SaslCredentials sasl, Controls controls) throws LDAPException Binds to the server using SASL authentication and controls. Parameters: dn - of manager sasl - credentials of manager controls - array of controls to send to server Throws: LDAPException - in the event of failure of the bind 3.11.15 search public SearchResults search(SearchSpec spec) throws LDAPException Requests an LDAP search to be performed using the supplied SearchSpec. Parameters: searchSpec - provides the base search constraints and any additional controls 3.11.16 search public SearchResults search(DN base, Scope scope, AliasDeref deref, int size_limit, int time_limit, boolean attrsOnly, Filter filter, AttributeDescription[] atts, Controls controls, Interaction y) throws LDAPException Requests a search with controls. Parameters: base - place in LDAP tree to start searching scope - Scope.BASE, Scope.ONELEVEL, Scope.SUBTREE deref_aliases - AliasDeref.NEVER, AliasDeref.SEARCHING, AliasDeref.FINDING, AliasDeref.ALWAYS size_limit - maximum number of entries to be returned time_limit - maximum number of seconds to wait for an answer attrsOnly - true = return attributes only filter - search criteria to use Expires 8/99 [Page 64] JAVA LDAP API February 1999 atts - array of attributes to return controls - array of controls to send to server Returns: SearchResults EntryEnumeration Throws: LDAPException - a generic exception 3.11.17 modify public ModifyResponse modify(DN base, ModifyOp op, AttributeSet attrs, Controls controls) throws LDAPException 3.11.18 modify public ModifyResponse modify(DN base, Modification[] mods, Controls controls) throws LDAPException Modifies an entry of a directory. Parameters: base - place in LDAP tree to modify mods - array of modifications to be made controls - array of controls to send to server Returns: ModifyResponse from server or null if error Throws: LDAPException - a generic exception 3.11.19 add public AddResponse add(DN entry, AttributeSet attrs, Controls controls) throws LDAPException An entry is added to the directory with the given distinguished name and Attributes. Optional controls may be supplied. Parameters: dn - of the entry to be added attrs - set of attributes to add under the given distinguished name controls - array of controls to send to server, or null Returns: Response from server or null if error Throws: LDAPException - a generic exception 3.11.20 delete public DelResponse delete(DN entry, Controls controls) throws LDAPException Expires 8/99 [Page 65] JAVA LDAP API February 1999 Deletes an Entry from the directory. Parameters: entry - to delete control - array of controls to send to server Returns: DeleteResponse from server or null if error Throws: LDAPException - a generic exception 3.11.21 modifyDN public ModifyDNResponse modifyDN(DN entry, RDN new_rdn, boolean delete_old, DN new_superior, Controls controls) throws LDAPException Requests a dn modification with controls. Parameters: base - place in LDAP tree to modify newRDN - array of new relative dn's delete_old - true = delete the old entry new_superior - new parent for entry controls - array of controls to send to server Returns: ModifyDNResponse from server or null if error Throws: LDAPException - a generic exception 3.11.22 compare public CompareResponse compare(DN entry, AttributeValueAssertion ava, Controls controls) throws LDAPException Requests a comparison with controls. Parameters: entry - dn of entry to compare ava - assertion of attribute to compare control - array of controls to send to server Returns: CompareResponse from server or null if error Throws: LDAPException - a generic exception Expires 8/99 [Page 66] JAVA LDAP API February 1999 3.11.23 abandon public void abandon(int message_id, Controls controls) throws LDAPException Requests an abandonment with controls. Parameters: message_id - of the operation to abandon. control - array of controls to send to server Throws: LDAPException - a generic exception 3.11.24 extendedRequest public ExtendedResponse extendedRequest(OID name, byte[] value) throws LDAPException Makes an extended request. Parameters: name - oid of the request value - of the request Returns: ExtendedResponse from server or null if error Throws: LDAPException - a generic exception 3.11.25 extendedRequest public ExtendedResponse extendedRequest(OID name, byte[] value, Controls controls) throws LDAPException Makes an extended request with controls. Parameters: name - oid of the request value - of the request control - array of controls to send to server Returns: ExtendedResponse from server or null if error Throws: LDAPException - a generic exception 3.11.26 issueExtended public ExtendedResponse issueExtended(org.ietf.ldap.apdu.ExtendedRequest exReq, Controls controls) Expires 8/99 [Page 67] JAVA LDAP API February 1999 throws LDAPException 3.12 Class org.ietf.ldap.client.DynamicRefreshResponse public class DynamicRefreshResponse extends ExtendedResponse This notification may be used by the server to advise the client that the server is about to close the connection due to an error condition. Note that this notification is NOT a response to an unbind requested by the client. This notification is intended to assist clients in distinguishing between an error condition and a transient network failure. As with a connection close due to network failure, the client MUST NOT assume that any outstanding requests which modified the directory have succeeded or failed. 3.12.1 Fields public static OID responseName 3.12.2 Constructors public DynamicRefreshResponse() public DynamicRefreshResponse(LDAPException ex, Referral ref) 3.12.3 toString public String toString() 3.13 Class org.ietf.ldap.client.ExtendedResponse Subclasses: DynamicRefreshResponse, StartTLSResponse, UnsolicitedNotification public class ExtendedResponse extends Response ExtendedResponse provides a way to implement new types of responses without changing the underlying LDAP protocol. Each extended response is required by RFC 2251 to have a unique OID that identifies the response. ExtendedResponse provides a registry that supports the construction of a specific extended response by the protocol decoder (ASN.1 interpreter). 3.13.1 Constructors public ExtendedResponse() This constructor must be present in each extended response so that .newInstance() can be called. Expires 8/99 [Page 68] JAVA LDAP API February 1999 public ExtendedResponse(LDAPException ex, Referral ref, OID responseName) public ExtendedResponse(LDAPException ex, Referral ref, OID responseName, byte[] response) 3.13.2 Register public static void register(OID oid, java.lang.Class c) Establishes the association of an OID for an extended response and the Class that implements the response. Each such response class must implement appropriate init(...) routines. Parameters: c - the Class implementing the extended response oid - the unique OID of the response 3.13.3 toExtended public static java.lang.Class toExtended(String oid) Returns the Class corresponding to the given OID Parameters: oid - the unique identifier of the response 3.13.4 init public void init(LDAPException ex, Referral ref, OID responseName) This method is called when constructing an instance of some class of extended response for which there is no response specific data. Thus the only information that is conveyed is the exception state, referral, and the OID name of the response Parameters: ex - the error information if any ref - the referral if any responseName - the OID of the response being initialized 3.13.5 init public void init(LDAPException ex, Referral ref, OID responseName, byte[] response) This method is used when there is additional initialization data specific to the extended response. The additional data is conveyed via a byte[] that contains the octets received via the LDAP protocol. It Expires 8/99 [Page 69] JAVA LDAP API February 1999 may need to be subjected to further decoding during initialization. This is a response dependent issue. Parameters: ex - error information if any ref - referral if any response - the response data as a byte[] responseName - the OID of the response 3.13.6 getResponseName public OID getResponseName() Returns the OID of the response. 3.14 Class org.ietf.ldap.client.ModifyDNResponse public class ModifyDNResponse extends Response CompareResponse models the response including Controls and messageId for a compare request. 3.14.1 Constructors ModifyDNResponse public ModifyDNResponse(LDAPException ex, Referral ref) 3.15 Class org.ietf.ldap.client.ModifyResponse public class ModifyResponse extends Response CompareResponse models the response including Controls and messageId for a compare request. 3.15.1 Constructors public ModifyResponse(LDAPException ex, Referral ref) 3.16 Class org.ietf.ldap.client.NoticeOfDisconnection public class NoticeOfDisconnection extends UnsolicitedNotification This notification may be used by the server to advise the client that the server is about to close the connection due to an error condition. Note that this notification is NOT a response to an unbind requested by the client. This notification is intended to assist clients in distinguishing between an error condition and a transient network failure. As with a connection close due to network failure, the client MUST NOT assume that any outstanding requests which modified the Expires 8/99 [Page 70] JAVA LDAP API February 1999 directory have succeeded or failed. 3.16.1 Fields public static OID responseName 3.16.2 Constructors public NoticeOfDisconnection() public NoticeOfDisconnection(LDAPException ex, Referral ref) 3.17 Class org.ietf.ldap.client.Response Subclasses: AddResponse, BindResponse, CompareResponse, DelResponse, ExtendedResponse, ModifyDNResponse, ModifyResponse, SearchDone public class Response extends Message Response is the super class of all the different LDAP response classes. It provides access to the LDAPException or Referral if any that result from an LDAP request. A Response that has no exception or referral is a successful response. 3.17.1 Constructors public Response() public Response(LDAPException ex, Referral ref) public Response(LDAPException ex, Referral ref, String message) 3.17.2 getMessage public String getMessage() 3.17.3 isSuccess public boolean isSuccess() 3.17.4 getException public LDAPException getException() 3.17.5 getReferral public Referral getReferral() 3.18 Class org.ietf.ldap.client.SearchDone public class SearchDone extends Response Expires 8/99 [Page 71] JAVA LDAP API February 1999 CompareResponse models the response including Controls and messageId for a compare request. 3.18.1 Constructors public SearchDone(LDAPException ex, Referral ref) 3.19 Class org.ietf.ldap.client.SearchEntry public class SearchEntry extends Message SearchEntry contains an single Entry resulting from a search 3.19.1 Constructors public SearchEntry(Entry entry) 3.19.2 getEntry public Entry getEntry() 3.20 Class org.ietf.ldap.client.SearchReference public class SearchReference extends Message SearchReference contains an reference to a location where more search results may be found. 3.20.1 Constructors public SearchReference(Continuation cont) 3.20.2 getContinuation public Continuation getContinuation() Returns the Continuation (URLList) for this SearchReference. 3.21 Class org.ietf.ldap.client.SearchResults public class SearchResults implements EntityEnumeration A SearchResults is returned by the search request on the DirectoryClient. SearchResults implements EntityEnumeration. The elements returned by a search may be accessed via: nextElement() returns an Object which is either an Entry or a Referral and may throw Expires 8/99 [Page 72] JAVA LDAP API February 1999 NoSuchElementException nextEntry() returns an Entry or throws either NoSuchElementException or one of the defined LDAPExceptions. next() returns an Entity or throws either NoSuchElementException or one of the defined LDAPExceptions. nextElement() implements the standard method of Enumeration and will require that its result be cast to the appropriate type to be used. nextEntry() is useful in the typical case when implicit referral handling is enabled and the user desires to process each of the entries from the search. Aside from the return type of this method, it differs from nextElement() in that it may throw an LDAP specific exception as well as NoSuchElementException. next() returns an Entity which is either an Entry or a Referral, and hence will be useful when !isReferring() and isReturnReferrals(). This method may also throw LDAP specific exceptions. There are two methods for testing whether the end of the SearchResults have been reached: hasMoreElements() conforming to the standard method of Enumeration; and hasMore() which allows for an LDAP specific exception to be thrown if appropriate. 3.21.1 Constructors SearchResults public SearchResults(ClientConnection conn, int messageId, Interaction x, SearchSpec spec) Constructs a SearchResults with the originating connection and messageId as well as an Interaction over which search results will arrive. Note that results may arrive from many different ClientConnections due to SearchReference processing. Parameters: conn - originating ClientConnection messageId - original messageId when search was initiated x - the Interaction over which results will arrive spec - the SearchSpec of the original arguments for the search SearchResults public SearchResults(ClientConnection conn, int messageId, Expires 8/99 [Page 73] JAVA LDAP API February 1999 Interaction x, BinderFactory bf, SearchSpec spec) Constructs a SearchResults with the originating connection and messageId as well as an Interaction over which search results will arrive. Note that results may arive from many different ClientConnections due to SearchReference processing. Parameters: conn - originating ClientConnection messageId - original messageId when search was initiated x - the Interaction over which results will arrive spec - the SearchSpec of the original arguments for the search 3.21.2 setBinderFactory public void setBinderFactory(BinderFactory bf) 3.21.3 getBinderFactory public BinderFactory getBinderFactory() 3.21.4 getInteraction public Interaction getInteraction() 3.21.5 abandon public void abandon() throws LDAPException Allows the user to gracefully terminate a search (and any in-progress sub-searches) of the directory. Throws: LDAPException - in the event of errors sending the abandon request 3.21.6 isReferring public boolean isReferring() Return whether referrals are implicitly followed are not. 3.21.7 setReferring public boolean setReferring(boolean referring) Set whether to follow referrals implicitly or not Returns: the previous state of referral following 3.21.8 isReturnReferrals Expires 8/99 [Page 74] JAVA LDAP API February 1999 public boolean isReturnReferrals() Indicate whether referrals are to be returned or if not-followed implicitly signalled via a ReferralException Returns: true if referrals are to be returned when not implicitly following referrals 3.21.9 setReturnReferrals public boolean setReturnReferrals(boolean returning) Set whether to return referrals or not Returns: previous state of returning referrals 3.21.10 getControls public Controls getControls() Returns the Controls for the current search result entry or search result reference. May be null if the current result is not defined or end of results has been reached. 3.21.11 hasMoreElements public boolean hasMoreElements() Implements Enumeration.hasMoreElements(). If there is an Entity (either an Entry or a Referral) available then it returns true otherwise false. This method may block until a result has been received or the end of the search has been detected (in brief by receiving a SearchResultDone from the server, but the condition may be much more complex owing to referral following). Returns: true if there are more search results; else false 3.21.12 hasMore public boolean hasMore() throws LDAPException Implements EntityEnumeration.hasMore(). If there is an Entry available then it returns true otherwise false. An LDAP specific exception may be thrown if the end of the search has been reached and either the final SearchResultDone signalled an exceptional condition or referral following led to an exceptional condition at some point, including referral following not being enabled and a SearchResultReference or SearchResultDone with a referral being received. This method may block until a result has been received or the end of Expires 8/99 [Page 75] JAVA LDAP API February 1999 the search has been detected (in brief by receiving a SearchResultDone from the server, but the condition may be much more complex owing to referral following). Returns: true if there are more search results; else false Throws: LDAPException - thrown on IOException and other times 3.21.13 nextElement public java.lang.Object nextElement() throws java.util.NoSuchElementException Implements Enumeration.nextElement(). An Object which is an Entity (either an Entry or a Referral) is returned or NoSuchElementException is thrown if the end of the search results has been reached. Any LDAP specific exceptions that have been accumulated during the search may be retrieved via inError() and getErrors(). This method may block until a result has been received or the end of the search has been detected (in brief by receiving a SearchResultDone from the server, but the condition may be much more complex owing to referral following). Returns: the next Entry or Referral Throws: java.util.NoSuchElementException - thrown at the completion of the search 3.21.14 next public Entity next() throws LDAPException, java.util.NoSuchElementException The semantics of this method are the same as nextElement() except that the return type is Entity and an LDAP specific exception may be thrown in the event that the end of the search has been reached and one or more LDAP specific exceptions occurred. This method may block until a result has been received or the end of the search has been detected (in brief by receiving a SearchResultDone from the server, but the condition may be much more complex owing to referral following). Returns: the next SearchResultEntry Throws: java.util.NoSuchElementException - thrown when server sends a SearchResultDone object indicating no more entries. Expires 8/99 [Page 76] JAVA LDAP API February 1999 LDAPException - thrown when LDAP specific errors occur. 3.21.15 nextEntry public Entry nextEntry() throws LDAPException, java.util.NoSuchElementException This method implements EntityEnumeration.nextEntry() and either returns an Entry or at the end of the search throws either NoSuchElementException or an LDAP specific exception if one occurred during the search. Returns: the next SearchResultEntry Throws: java.util.NoSuchElementException - thrown when server sends a SearchResultDone object indicating no more entries. LDAPException - thrown when LDAP specific errors occur. 3.21.16 inError public boolean inError() Returns true if errors have been encountered during processing of this search. There may be multiple errors owing to the possibility of multiple sub-searches arising during implicit referral following. 3.21.17 getErrors public java.util.Vector getErrors() Returns the list of LDAPExceptions encountered during processing of the search. 3.22 Class org.ietf.ldap.client.SearchSpec public class SearchSpec implements java.lang.Cloneable The SearchSpec provides a convenient way to bundle the various parameters to an LDAP search so that they may be used with more than one connection or multiple times with same connection. A SearchSpec may be cloned to and a complete set of accessors and setters are provided. 3.22.1 Constructors public SearchSpec() Constructs the default search spec that will retrieve the root dse for a server. Expires 8/99 [Page 77] JAVA LDAP API February 1999 public SearchSpec(DN base, Scope scope, AliasDeref deref, int sizeLimit, int timeLimit, boolean attrsOnly, Filter filter, AttributeDescription[] atts, int psz, Controls cntrls) 3.22.2 base public DN base() 3.22.3 scope public Scope scope() 3.22.4 deref public AliasDeref deref() 3.22.5 size_limit public int size_limit() 3.22.6 time_limit public int time_limit() 3.22.7 pageSize public int pageSize() 3.22.8 pageHandler public PageHandler pageHandler() 3.22.9 attrsOnly public boolean attrsOnly() 3.22.10 filter public Filter filter() 3.22.11 attrs public AttributeDescription[] attrs() 3.22.12 controls public Controls controls() Expires 8/99 [Page 78] JAVA LDAP API February 1999 3.22.13 setBase public void setBase(DN b) 3.22.14 setScope public void setScope(Scope s) 3.22.15 setDeref public void setDeref(AliasDeref ad) 3.22.16 setSizeLimit public void setSizeLimit(int sl) 3.22.17 setTimeLimit public void setTimeLimit(int tl) 3.22.18 setPageSize public void setPageSize(int p) 3.22.19 setPageHandler public void setPageHandler(PageHandler ph) 3.22.20 setAttrsOnly public void setAttrsOnly(boolean ao) 3.22.21 setFilter public void setFilter(Filter f) 3.22.22 setAttrs public void setAttrs(AttributeDescription[] a) 3.22.23 setControls public void setControls(Controls c) 3.23 Class org.ietf.ldap.client.StartTLSResponse public class StartTLSResponse extends ExtendedResponse This notification may be used by the server to advise the client of the status of a request to initiate TLS negotiations on the current connection. Expires 8/99 [Page 79] JAVA LDAP API February 1999 3.23.1 Fields public static OID responseName 3.23.2 Constructors public StartTLSResponse() public StartTLSResponse(LDAPException ex, Referral ref) 3.24 Class org.ietf.ldap.client.UnsolicitedNotification Subclasses: NoticeOfDisconnection public class UnsolicitedNotification extends ExtendedResponse An UnsolicitedNotification is an LDAPMessage sent from the server to the client which is not in response to any LDAPMessage received by the server. It is used to signal an extraordinary condition in the server or in the connection between the client and the server. The notification is of an advisory nature, and the server will not expect any response to be returned from the client. 3.24.1 Constructors public UnsolicitedNotification() public UnsolicitedNotification(LDAPException ex, Referral ref, OID responseName) 3.25 Class org.ietf.ldap.client.V2DirectoryClient Subclasses: DirectoryClient public class V2DirectoryClient Provides a simple synchronous(blocking) interface to an LDAP v2 Directory. Through a DirectoryClient, a user can issue the various requests specified in RFC 1777: bind, unbind, search, modify, modify dn, compare, add, del The abandon operation is not supported since this class is a blocking interface to the directory. The one exception to this is the search Expires 8/99 [Page 80] JAVA LDAP API February 1999 which returns a SearchResults immediately; however, this class does provide an abandon() method that will abandon all search activities that may be in progress for the given SearchResults. 3.25.1 Constructors public V2DirectoryClient() public V2DirectoryClient(String host, int port) throws LDAPException Establishes a ClientConnection to the specified host and port as the underlying connection for this DirectoryClient public V2DirectoryClient(ClientConnection con) Constructs a new DirectoryClient with the underlying ClientConnection 3.25.2 getProtocolVersion public int getProtocolVersion() Returns the protocol version in use. This is overridden in subclasses for other (3) protocol versions. 3.25.3 getHost public String getHost() Returns the name of the host that was contacted to establish the underlying ClientConnection 3.25.4 getPort public int getPort() Returns the port that was contacted to establish the underlying ClientConnection 3.25.5 getClientConnection public ClientConnection getClientConnection() Returns the ClientConnection for this DirectoryClient 3.25.6 getSearchSpec public SearchSpec getSearchSpec() Returns the current SearchSpec that represents the defaults for searches initiated through this connection. 3.25.7 setSearchSpec Expires 8/99 [Page 81] JAVA LDAP API February 1999 public SearchSpec setSearchSpec(SearchSpec spec) Set the current SearchSpec that represents the defaults for searches initiated through this connection. Returns the previous SearchSpec. 3.25.8 getTimeLimit public int getTimeLimit() Returns the amount of time that the interface will wait for a response to a request. A value of 0(zero) indicates that no time limit is in effect. Note that this is different from the SearchSpec.getTimeLimit() which is the maximum amount of time that the server is to spend on a search. This timeLimit applies to the maximum time in seconds before the DirectoryClient will throw an InterfaceTimeLimitException. 3.25.9 setTimeLimit public void setTimeLimit(int newTL) Sets the time limit to be applied to all operations initiated via this DirectoryClient Parameters: newTL - the time limit to impose on operations 3.25.10 getHopLimit public int getHopLimit() 3.25.11 setHopLimit public void setHopLimit(int hops) Sets the hop limit to be applied to all operations initiated via this DirectoryClient. The hop limit constrains the number of steps of referral following that the interface will perform before throwing a HopLimitException. The hop limit defaults to 10. Parameters: newTL - the hop limit to impose on operations 3.25.12 isReferring public boolean isReferring() Return whether referrals are implicitly followed or not Expires 8/99 [Page 82] JAVA LDAP API February 1999 3.25.13 isReturnReferrals public boolean isReturnReferrals() Return true if referrals are to be returned when not implicitly following referrals 3.25.14 performReferral public Response performReferral(Response msg) throws ReferralException, ProtocolException LDAP v2 doesn't permit referrals so this method simply returns its argument. This method is specialized in DirectoryClient to actually provide for referral handling. Parameters: msg - the response, possibly a referral Returns: the response argument 3.25.15 bind public BindResponse bind(String dn, String password) throws LDAPException Binds to the server using simple authentication. Parameters: name - of manager password - of manager Throws: LDAPException - a generic exception 3.25.16 bind public BindResponse bind(DN dn, String password) throws LDAPException Binds to the server using simple authentication. Parameters: dn - of manager password - of manager Throws: LDAPException - a generic exception 3.25.17 unbind public void unbind() throws LDAPException Expires 8/99 [Page 83] JAVA LDAP API February 1999 Unbinds from the server. Throws: LDAPException - a generic exception 3.25.18 search public SearchResults search(String base, Scope scope, String filter, String[] attrs, boolean attrsOnly) throws LDAPException Corresponds to ldap_search_s of the C api except that a asynchronous SearchResults is returned rather than waiting for all the results before proceeding Parameters: base - the distinguished name t