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 to base the search scope - one of Scope.BASE, Scope.ONELEVEL, or Scope.SUBTREE filter - a string conforming to RFC 2254 expressing the filter to use attrs - a list of the attribute description strings of the attributes to return attrsOnly - true if only the attribute values should be returned Returns: the SearchResults of the search Throws: LDAPException - thrown if an error occurs during the search or processing of the filter of base 3.25.19 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, if any controls are present they are ignored. 3.25.20 search public SearchResults search(DN base, Scope scope, AliasDeref deref, int size_limit, int time_limit, boolean attrsOnly, Filter filter, AttributeDescription[] atts) Expires 8/99 [Page 84] JAVA LDAP API February 1999 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 time_limit - maximum number of seconds to wait for an answer attrsOnly - true = return attributes only filter - search criteria to use atts - array of attributes to return Returns: SearchResults EntryEnumeration Throws LDAPException - a generic exception 3.25.21 modify public ModifyResponse modify(DN base, ModifyOp op, Attribute attr) throws LDAPException 3.25.22 modify public ModifyResponse modify(DN base, ModifyOp op, AttributeSet attrs) throws LDAPException 3.25.23 modify public ModifyResponse modify(DN base, Modification[] mods) throws LDAPException Requests the modification of an Entry. Parameters: base - place in LDAP tree to modify mods - array of modifications to be made Returns: ModifyResponse from server or null if error Throws: LDAPException - typically signalling a protocol error 3.25.24 add public AddResponse add(Entry entry) throws LDAPException An Entry is added to the directory. The Entry supplies the distinguished name and attributes that constitute the new entry. Expires 8/99 [Page 85] JAVA LDAP API February 1999 Parameters: entry - to be added Returns: Response from server or null if error Throws: LDAPException - a generic exception 3.25.25 add public AddResponse add(DN dn, AttributeSet attrs) throws LDAPException An entry is added to the directory with the given distinguished name and Attributes. Parameters: dn - of the entry to be added attrs - set of attributes to add under the given distinguished name Returns: Response from server or null if error Throws: LDAPException - a generic exception 3.25.26 delete public DelResponse delete(DN entry) throws LDAPException Deletes an Entry from the directory Parameters: entry - to delete Returns: DeleteResponse from server or null if error Throws: LDAPException - a generic exception 3.25.27 modifyDN public ModifyDNResponse modifyDN(DN entry, RDN new_rdn, boolean delete_old, DN new_superior) throws LDAPException Requests a dn modification: either modifying the leftmost RDN of an Entry or moving a sub-tree rooted at new_superior. Parameters: entry - place in LDAP tree to modify newRDN - new relative dn's Expires 8/99 [Page 86] JAVA LDAP API February 1999 delete_old - true if the old entry is to be deleted new_superior - new parent for entry Returns: ModifyDNResponse from server or null if error Throws: LDAPException - a generic exception 3.25.28 compare public CompareResponse compare(DN entry, AttributeValueAssertion ava) throws LDAPException Requests a comparison. Parameters: entry - dn of entry to compare ava - assertion of attribute to compare Returns: CompareResponse from server or null if error Throws: LDAPException - a generic exception 3.25.29 abandon public void abandon(int message_id) throws LDAPException Requests an abandonment. Parameters: message_id - of the operation to abandon. control - array of controls to send to server Throws: LDAPException - a generic exception 3.26 Class org.ietf.ldap.client. AdministrationLimitExceededException public class AdministrationLimitExceededException extends ProtocolException Exception thrown by client operations when the result code returned from the server is adminLimitExceeded 3.26.1 Constructors public AdministrationLimitExceededException() public AdministrationLimitExceededException(String s) 3.27 Class org.ietf.ldap.client.AffectsMultipleDSAsException Expires 8/99 [Page 87] JAVA LDAP API February 1999 public class AffectsMultipleDSAsException extends ProtocolException Exception thrown by client operations when the result code returned from the server is affectsMultipleDSAs. 3.27.1 Constructors public AffectsMultipleDSAsException() public AffectsMultipleDSAsException(String s) 3.28 Class org.ietf.ldap.client.AliasDereferencingProblemException public class AliasDereferencingProblemException extends MatchedDNException Exception thrown by client operations when the result code returned from the server is aliasDereferencingProblem. 3.28.1 Constructors public AliasDereferencingProblemException(String s, DN matchedDN) 3.29 Class org.ietf.ldap.client.AliasProblemException public class AliasProblemException extends MatchedDNException Exception thrown by client operations when the result code returned from the server is aliasProblem. 3.29.1 Constructors public AliasProblemException(String s, DN matchedDN) 3.30 Class org.ietf.ldap.client.AttributeOrValueExistsException public class AttributeOrValueExistsException extends ProtocolException Exception thrown by client operations when the result code returned from the server is attributeOrValueExists. 3.30.1 Constructors public AttributeOrValueExistsException() public AttributeOrValueExistsException(String s) 3.31 Class org.ietf.ldap.client.AuthenticationMethodNotSupportedException public class AuthenticationMethodNotSupportedException Expires 8/99 [Page 88] JAVA LDAP API February 1999 extends ProtocolException Exception thrown by client operations when the result code returned from the server is authenticationMethodNotSupported. 3.31.1 Constructors public AuthenticationMethodNotSupportedException() public AuthenticationMethodNotSupportedException(String s) 3.32 Class org.ietf.ldap.client.BusyException public class BusyException extends ProtocolException Exception thrown by client operations when the result code returned from the server is busy. 3.32.1 Constructors public BusyException() public BusyException(String s) 3.33 Class org.ietf.ldap.client.ConfidentialityRequiredException public class ConfidentialityRequiredException extends ProtocolException Exception thrown by client operations when the result code returned from the server is confidentialityRequired. 3.33.1 Constructors public ConfidentialityRequiredException() public ConfidentialityRequiredException(String s) 3.34 Class org.ietf.ldap.client.ConstraintViolationException public class ConstraintViolationException extends ProtocolException Exception thrown by client operations when the result code returned from the server is constraintViolation. 3.34.1 Constructors public ConstraintViolationException() public ConstraintViolationException(String s) 3.35 Class org.ietf.ldap.client.DisconnectionException Expires 8/99 [Page 89] JAVA LDAP API February 1999 public class DisconnectionException extends ProtocolException A DisconnectionException is thrown in the case that an ExtendedResponse is received that has messageId == 0 and the responseName is 1.3.6.1.4.1.1466.20036. Due to the asynchronous support in the SDK a response message may be received and enqueued for processing well in advance of when it is actually selected for processing. Delaying the signalling of the exception until processing makes it easier to process protocol and related interface events in the order in which they occurred. In other words there is no out of band signalling of exceptions. 3.35.1 Constructors public DisconnectionException() public DisconnectionException(String s) 3.36 Class org.ietf.ldap.client.EntryAlreadyExistsException public class EntryAlreadyExistsException extends ProtocolException Exception thrown by client operations when the result code returned from the server is entryAlreadyExists. 3.36.1 Constructors public EntryAlreadyExistsException() public EntryAlreadyExistsException(String s) 3.37 Class org.ietf.ldap.client.InappropriateAuthenticationException public class InappropriateAuthenticationException extends ProtocolException Exception thrown by client operations when the result code returned from the server is inappropriateAuthentication. 3.37.1 Constructors public InappropriateAuthenticationException() public InappropriateAuthenticationException(String s) 3.38 Class org.ietf.ldap.client.InappropriateMatchingException public class InappropriateMatchingException extends ProtocolException Expires 8/99 [Page 90] JAVA LDAP API February 1999 Exception thrown by client operations when the result code returned from the server is inappropriateMatching. 3.38.1 Constructors public InappropriateMatchingException() public InappropriateMatchingException(String s) 3.39 Class org.ietf.ldap.client.InsufficientAccessRightsException public class InsufficientAccessRightsException extends ProtocolException Exception thrown by client operations when the result code returned from the server is insufficientAccessRights. 3.39.1 Constructors public InsufficientAccessRightsException() public InsufficientAccessRightsException(String s) 3.40 Class org.ietf.ldap.client.InvalidAttributeSyntaxException public class InvalidAttributeSyntaxException extends ProtocolException Exception thrown by client operations when the result code returned from the server is invalidAttributeSyntax. 3.40.1 Constructors public InvalidAttributeSyntaxException() public InvalidAttributeSyntaxException(String s) 3.41 Class org.ietf.ldap.client.InvalidCredentialsException public class InvalidCredentialsException extends ProtocolException Exception thrown by client operations when the result code returned from the server is invalidCredentials. 3.41.1 Constructors public InvalidCredentialsException() public InvalidCredentialsException(String s) 3.42 Class org.ietf.ldap.client.InvalidDNSyntaxException public class InvalidDNSyntaxException Expires 8/99 [Page 91] JAVA LDAP API February 1999 extends MatchedDNException Exception thrown by client operations when the result code returned from the server is invalidDNSyntax. 3.42.1 Constructors public InvalidDNSyntaxException(String s, DN matchedDN) 3.43 Class org.ietf.ldap.client.LDAPURLExtensionNotSupportedException public class LDAPURLExtensionNotSupportedException extends InterfaceException This exception is thrown by an application if it attempts to process an LDAP URL containing a critical extension which is not supported as specified in RFC 2255. 3.43.1 Constructors public LDAPURLExtensionNotSupportedException() public LDAPURLExtensionNotSupportedException(String s) 3.44 Class org.ietf.ldap.client.LoopDetectException public class LoopDetectException extends ProtocolException Exception thrown by client operations when the result code returned from the server is loopDetect 3.44.1 Constructors public LoopDetectException() LoopDetectException public LoopDetectException(String s) 3.45 Class org.ietf.ldap.client.MatchedDNException Subclasses: AliasDereferencingProblemException, AliasProblemException, InvalidDNSyntaxException, NoSuchObjectException public class MatchedDNException extends ProtocolException This exception is the root of a sub-tree of the exceptions that contain a matchedDN property. This exception is not itself generated within the interface and hence never thrown. See its subclasses. 3.45.1 Constructors Expires 8/99 [Page 92] JAVA LDAP API February 1999 public MatchedDNException(String s, DN matchedDN) 3.45.2 getMatchedDN public DN getMatchedDN() 3.46 Class org.ietf.ldap.client.NamingViolationException public class NamingViolationException extends ProtocolException Exception thrown by client operations when the result code returned from the server is namingViolation. 3.46.1 Constructors public NamingViolationException() public NamingViolationException(String s) 3.47 Class org.ietf.ldap.client.NoSuchAttributeException public class NoSuchAttributeException extends ProtocolException Exception thrown by client operations when the result code returned from the server is noSuchAttribute. 3.47.1 Constructors public NoSuchAttributeException() public NoSuchAttributeException(String s) 3.48 Class org.ietf.ldap.client.NoSuchObjectException public class NoSuchObjectException extends MatchedDNException Exception thrown by client operations when the result code returned from the server is noSuchObject. 3.48.1 Constructors public NoSuchObjectException(String s, DN matchedDN) 3.49 Class org.ietf.ldap.client.NotAllowedOnNonLeafException public class NotAllowedOnNonLeafException extends ProtocolException Exception thrown by client operations when the result code returned from the server is notAllowedOnNonLeaf. Expires 8/99 [Page 93] JAVA LDAP API February 1999 3.49.1 Constructors public NotAllowedOnNonLeafException() public NotAllowedOnNonLeafException(String s) 3.50 Class org.ietf.ldap.client.NotAllowedOnRDNException public class NotAllowedOnRDNException extends ProtocolException Exception thrown by client operations when the result code returned from the server is notAllowedOnRDN. 3.50.1 Constructors public NotAllowedOnRDNException() public NotAllowedOnRDNException(String s) 3.51 Class org.ietf.ldap.client.ObjectClassModificationsProhibitedException public class ObjectClassModificationsProhibitedException extends ProtocolException Exception thrown by client operations when the result code returned from the server is objectClassModificationsProhibited. 3.51.1 Constructors public ObjectClassModificationsProhibitedException() public ObjectClassModificationsProhibitedException(String s) 3.52 Class org.ietf.ldap.client.ObjectClassViolationException public class ObjectClassViolationException extends ProtocolException Exception thrown by client operations when the result code returned from the server is objectClassViolation. 3.52.1 Constructors public ObjectClassViolationException() public ObjectClassViolationException(String s) 3.53 Class org.ietf.ldap.client.OperationsErrorException public class OperationsErrorException extends ProtocolException Expires 8/99 [Page 94] JAVA LDAP API February 1999 Exception thrown by client operations when the result code returned from the server is operationsError. 3.53.1 Constructors public OperationsErrorException() public OperationsErrorException(String s) 3.54 Class org.ietf.ldap.client.OtherException public class OtherException extends ProtocolException Exception thrown by client operations when the result code returned from the server is other. 3.54.1 Constructors public OtherException() public OtherException(String s) 3.55 Class org.ietf.ldap.client.ProtocolErrorException public class ProtocolErrorException extends ProtocolException Exception thrown by client operations when the result code returned from the server is protocolError. 3.55.1 Constructors public ProtocolErrorException() public ProtocolErrorException(String s) 3.56 Class org.ietf.ldap.client.ReferralException public class ReferralException extends InterfaceException ReferralException is thrown in the event that either a Referral Result or a SearchResultReference is received on a ClientConnection and referral processing is not enabled on that ClientConnection. 3.56.1 Constructors public ReferralException() public ReferralException(String s) 3.57 Class org.ietf.ldap.client.SizeLimitExceededException Expires 8/99 [Page 95] JAVA LDAP API February 1999 public class SizeLimitExceededException extends ProtocolException This exception is thrown when a response Message is processed that contains an LDAPResult that signals sizeLimitExceeded. Due to the asynchronous support in the SDK a response message may be received and enqueued for processing well in advance of when it is actually selected for processing. Delaying the signalling of the exception until processing makes it easier to process protocol and related interface events in the order in which they occurred. In other words there is no out of band signalling of exceptions. 3.57.1 Constructors public SizeLimitExceededException() public SizeLimitExceededException(String s) 3.58 Class org.ietf.ldap.client.StrongAuthRequiredException public class StrongAuthenticationRequiredException extends ProtocolException Exception thrown by client operations when the result code returned from the server is strongAuthenticationRequired. 3.58.1 Constructors public StrongAuthenticationRequiredException() public StrongAuthenticationRequiredException(String s) 3.59 Class org.ietf.ldap.client.TimeLimitExceededException public class TimeLimitExceededException extends ProtocolException Exception thrown by client operations when the result code returned from the server is timeLimitExceeded 3.59.1 Constructors public TimeLimitExceededException() public TimeLimitExceededException(String s) 3.60 Class org.ietf.ldap.client.UnavailableCriticalExtensionException public class UnavailableCriticalExtensionException extends ProtocolException Exception thrown by client operations when the result code returned Expires 8/99 [Page 96] JAVA LDAP API February 1999 from the server is unavailableCriticalExtension. 3.60.1 Constructors public UnavailableCriticalExtensionException() public UnavailableCriticalExtensionException(String s) 3.61 Class org.ietf.ldap.client.UnavailableException public class UnavailableException extends ProtocolException Exception thrown by client operations when the result code returned from the server is unavailable. 3.61.1 Constructors public UnavailableException() public UnavailableException(String s) 3.62 Class org.ietf.ldap.client.UndefinedAttributeTypeException public class UndefinedAttributeTypeException extends ProtocolException Exception thrown by client operations when the result code returned from the server is undefinedAttributeType. 3.62.1 Constructors public UndefinedAttributeTypeException() public UndefinedAttributeTypeException(String s) 3.63 Class org.ietf.ldap.client.UnwillingToPerformException public class UnwillingToPerformException extends ProtocolException Exception thrown by client operations when the result code returned from the server is unwillingToPerform. 3.63.1 Constructors public UnwillingToPerformException() public UnwillingToPerformException(String s) 4. Package org.ietf.ldap.ldif 4.0.1 Description Expires 8/99 [Page 97] JAVA LDAP API February 1999 Provides classes that implement reading and writing LDAP Interchange Format streams. The principal classes are LDIFReader and LDIFWriter. These classes are used in the translation between LDIF to and from Record objects. Records are composed of a directory name and a RecordContent object, which is an abstract class subclassed as an AddRecordContent, AttributeRecordContent, DeleteRecordContent, ModifyDNRecordContent, or ModifyRecordContent. RecordContent stores information about the change type (or information in the case of AttributeRecordContent) specified by the LDIF record. 4.1 Class org.ietf.ldap.ldif.AddRecordContent public class AddRecordContent extends RecordContent A subtype of RecordContent which stores attribute content to be added to an LDAP directory element. 4.1.1 Constructors public AddRecordContent() public AddRecordContent(Attribute attribute) Parameters: attribute - an Attribute to be added to an existing LDAP directory entry public AddRecordContent(Attribute[] attributes) Parameters: attribute - an array of Attributes to be added 4.1.2 toString public String toString() Returns: an LDIF String representation. 4.1.3 addAttribute public void addAttribute(Attribute attribute) Adds an Attribute element to the list of Attributes to be added to an existing LDAP directory entry. Parameters: attribute - the Attribute to be added to the entry 4.1.4 getAttributes public Attribute[] getAttributes() Expires 8/99 [Page 98] JAVA LDAP API February 1999 Returns: an array of Attribute objects to be added to an existing LDAPdirectory 4.1.5 addElement public void addElement(String element) throws ParseException Parameters: element - A line of text to be parsed. Since this object stores attribute additions, element should be a parsable LDIF String, an attribute to be added to an existing LDAP directory entry. Throws: ParseException - If error reading the input element 4.2 Class org.ietf.ldap.ldif.AttributeRecordContent public class AttributeRecordContent extends RecordContent A subtype of RecordContent which stores records of attributes, used when adding entries to a directory remotely. 4.2.1 Constructors public AttributeRecordContent() public AttributeRecordContent(Attribute attribute) public AttributeRecordContent(AttributeSet attributes) 4.2.2 toString public String toString() Returns: an LDIF String representation. 4.2.3 addAttribute public void addAttribute(Attribute attribute) Parameters: attribute - the attribute to add 4.2.4 getAttributes public Attribute[] getAttributes() Returns: an array of Attributes 4.2.5 addElement Expires 8/99 [Page 99] JAVA LDAP API February 1999 public void addElement(String element) throws ParseException Parameters: element - A line of text to be parsed. Since this object stores attributes, element should be a String representation of an attribute. Throws: ParseException - If error reading the input element 4.3 Class org.ietf.ldap.ldif.DeleteRecordContent public class DeleteRecordContent extends RecordContent A subtype of RecordContent. Since there is no content for a deletion record, this class doesn't do much. 4.3.1 toString public String toString() Returns: a String representation of itself 4.3.2 addElement public void addElement(String ignored) throws ParseException Since it is undefined to add elements to a delete record, just throw an exception. Throws: ParseException - Always thrown since it is undefined to add elements to a DeleteRecordContent. 4.4 Class org.ietf.ldap.ldif.LDIFReader public class LDIFReader LDIFReader reads LDIF information from either the keyboard or file, creating Record objects which can be retrieved by calling read(). 4.4.1 Constructors public LDIFReader(java.io.File f) throws java.io.FileNotFoundException Constructs an instance which reads LDIF information read from the File parameter. Parameters: f - File object from which to read LDIF information. Expires 8/99 [Page 100] JAVA LDAP API February 1999 Throws: java.io.FileNotFoundException - If there is a problem using File public LDIFReader(java.io.InputStream is) Constructs an instance which reads LDIF information read from the File parameter. Parameters: is - InputStream from which to read LDIF content. 4.4.2 read public Record read() throws ParseException Reads a Record from the input stream set at construction time. Returns: Record from input stream. Null if end of input file or if "#quit" is encountered. Throws: ParseException - If a syntax error is detected. 4.4.3 getVersion public int getVersion() Returns: int representing version of LDIF input (defaults to 0) 4.5 Class org.ietf.ldap.ldif.LDIFWriter public class LDIFWriter LDIFWriter serializes Record objects according to LDIF syntax onto an OutputStream. 4.5.1 Constructors public LDIFWriter(java.io.OutputStream os) Parameters: os - OutputStream to which to write LDIF information public LDIFWriter(java.io.File f) throws java.io.IOException Parameters: f - File to which to write LDIF information. Throws: java.io.IOException - If the File cannot be created. Expires 8/99 [Page 101] JAVA LDAP API February 1999 4.5.2 write public void write(Record record) throws java.io.IOException ProtocolException Writes a Record object directly to the output stream. Note: a given LDIF file is either a series of directory entries (Records with AttributeRecordContent set), or a series of modifications (Records with AddRecordContent, DeleteRecordContent, ModifyRecordContent, or ModifyDNRecordContent. An LDIF file MUST NOT contain both types of records. An attempt to deviate from this protocol will result in an exception. Parameters: record - to be written Throws: java.io.IOException - on error during writing ProtocolException - If an attempt is made to combine a set of directory entries with directory change records 4.5.3 write public void write(Entry entry) throws java.io.IOException Writes an Entry object directly to the output stream. Parameters: entry - to be written Throws: java.io.IOException - If there is a problem LDIF writing information to the output source 4.5.4 close public void close() throws java.io.IOException Closes the underlying OutputStream. 4.5.5 isSafe public static boolean isSafe(String s) Tests the "safety" of a string to be written. Returns false if the String should be base-64 encoded before being written. Parameters: s - the String to test 4.6 Class org.ietf.ldap.ldif.ModifyDNRecordContent Expires 8/99 [Page 102] JAVA LDAP API February 1999 public class ModifyDNRecordContent extends RecordContent A subtype of RecordContent. Stores information specific to an LDIF dn modification record. 4.6.1 Constructors public ModifyDNRecordContent() Constructs a default instance. public ModifyDNRecordContent(RDN new_rdn, boolean delete_old_rdn, DN new_superior) Constructs an instance with specified information. 4.6.2 toString public String toString() Returns: a String representation of itself in LDIF 4.6.3 setNewRDN public void setNewRDN(RDN new_rdn) Sets the new rdn value of the entry to set when making the modification. Parameters: new_rdn - String representing new rdn 4.6.4 getNewRDN public RDN getNewRDN() Returns: String representing new rdn value to set when making the modification 4.6.5 setDeleteOldRDN public void setDeleteOldRDN(boolean delete_old_rdn) Sets the contents of the delete old rdn value which describes what to do about the old rdn when making the modification. Parameters: delete_old_rdn - boolean representing said flag in an LDAP modify dn message operation 4.6.6 getDeleteOldRDN Expires 8/99 [Page 103] JAVA LDAP API February 1999 public boolean getDeleteOldRDN() Returns: boolean representing whether of not to delete old rdn when making the modification. 4.6.7 setNewSuperior public void setNewSuperior(DN new_superior) Sets the new superior value of the entry when making the modification. This optional parameter may be null, meaning keep the same parent of the entry being modified. A blank DN is used to indicate the the entry should be moved below the root entry. Parameters: new_superior - DN representing said information in an LDAP modify dn message operation 4.6.8 getNewSuperior public DN getNewSuperior() Returns: DN representing the new superior value of the entry when making the modification. This optional parameter may be null, meaning keep the same parent of the entry being modified. A blank DN is used to indicate the the entry should be moved below the root entry. 4.6.9 addElement public void addElement(String element) throws ParseException Parses the input String and sets relevant dn modification parameters represented in this object. Parameters: element - A String containing some information relevant to a dn modification operation in LDIF format Throws: ParseException - If there is an error reading the input element 4.7 Class org.ietf.ldap.ldif.ModifyRecordContent public class ModifyRecordContent extends RecordContent A subtype of RecordContent which stores the modification content of an LDAP element to be modified. 4.7.1 Constructors Expires 8/99 [Page 104] JAVA LDAP API February 1999 public ModifyRecordContent() public ModifyRecordContent(Modification modification) public ModifyRecordContent(Modification[] modifications) 4.7.2 toString public String toString() Returns: an String representation of itself in LDIF 4.7.3 addModification public void addModification(Modification modification) Adds an Modification element to be represented Parameters: modification - the modification to add 4.7.4 getModifications public Modification[] getModifications() Returns: an array of Modification objects stored in this object. 4.7.5 addElement public void addElement(String element) throws ParseException Parameters: element - A line of text to be parsed. Since this object stores modifications, element should be a String representation of an modification or separator (-) as specified by LDIF. Throws: ParseException - If error reading input element 4.8 Class org.ietf.ldap.ldif.Record public class Record Record is an object created by an LDIFReader when parsing LDIF information. It consists of a dn and and an object implementing the RecordContent interface, which represents record specific information. 4.8.1 Constructors public Record(DN dn) public Record(DN dn, RecordContent rc) Expires 8/99 [Page 105] JAVA LDAP API February 1999 4.8.2 toString public String toString() Returns: a String representation of itself in LDIF 4.8.3 setContent public void setContent(RecordContent content) Sets the RecordContent to content. 4.8.4 getDN public DN getDN() Returns: DN of directory entry referred to by this record. 4.8.5 getContent public RecordContent getContent() Returns: RecordContent object which specifies change type specific information. 4.9 Class org.ietf.ldap.ldif.RecordContent Subclasses: AddRecordContent, AttributeRecordContent, DeleteRecordContent, ModifyDNRecordContent, ModifyRecordContent public abstract class RecordContent RecordContent is an abstract class which specifies information specific to change operations add, delete, modify, and modify dn. 4.9.1 Fields public static final int CONTENT_UNDEFINED public static final int CONTENT_ADD public static final int CONTENT_DELETE public static final int CONTENT_MODIFY public static final int CONTENT_MODIFY_DN public static final int CONTENT_ATTRIBUTES 4.9.2 Constructors public RecordContent(int type) Expires 8/99 [Page 106] JAVA LDAP API February 1999 Constructs an instance of the specified type. 4.9.3 getType public int getType() Returns: an integer representing the type of this instance. Use public constants CONTENT_ADD, CONTENT_DELETE, CONTENT_MODIFY, CONTENT_MODIFY_DN, CONTENT_ATTRIBUTES for comparison. 4.9.4 toString public abstract String toString() Returns: a String repesentation of itself in LDIF 4.9.5 addElement public abstract void addElement(String element) throws ParseException Adds the element to the record content. Parameters: element - String of content specific information to be parsed. The action taken is dependent on the specific subclass of RecordContent. Throws: ParseException - if there is a syntax error in the input String 5. Package org.ietf.ldap.schema 5.0.1 Description Provides classes that implement the components of the schema on LDAP servers representing Attributes, Objectclasses, and MatchingRules. 5.1 Class org.ietf.ldap.schema.AttributeDefinition public class AttributeDefinition extends SchemaDefinition AttributeDefinition represents the Attribute Types as part of an LDAP schema defined in section 4.2 of RFC 2252. Attribute type definitions identify the object identifier by which an attribute is known, its syntax, associated matching rules, whether it is an operational attribute and if so its type, whether it is a collective attribute, whether it is permitted to have multiple values and whether or not it is derived from another attribute type. 5.1.1 Fields public static final String TYPE Expires 8/99 [Page 107] JAVA LDAP API February 1999 5.1.2 Constructors public AttributeDefinition(String value) throws ProtocolException Constructs an instance from a String containing terminal symbols and variables as specified in section 4.2 of RFC 2252. Parameters: value - the String containing information to be parsed Throws: ProtocolException - If there is a problem with the data in value AttributeDefinition public AttributeDefinition(AttributeType oid) Constructs an instance from specified parameters Parameters: oid - AttributeType representing the oid of this attribute 5.1.3 toString public String toString() Returns: a String representation of itself, suitable for storing back in directory. 5.1.4 toAttribute public Attribute toAttribute() Returns: an Attribute which contains the type and value of this definition 5.1.5 getOid public AttributeType getOid() Returns: AttributeType representing the oid of the attribute defined here 5.1.6 getNames public String[] getNames() Returns: an array of Strings representing the names by which this attribute is known. Since this field is optional, this method may return null. 5.1.7 setNames Expires 8/99 [Page 108] JAVA LDAP API February 1999 public void setNames(String[] names) Parameters: names - an array of Strings representing the names by which this attribute is known. 5.1.8 getDescription public String getDescription() Returns: a String representing a verbose description of this attribute. Since this field is optional, this method may return null. 5.1.9 setDescription public void setDescription(String description) Parameters: description - a String representing a verbose description of this attribute. 5.1.10 isObsolete public boolean isObsolete() Returns: true if this attribute is being phased out; false otherwise; default is false 5.1.11 setObsolete public void setObsolete(boolean isObsolete) Parameters: isObsolete - true if this attribute is being phased out; false otherwise; 5.1.12 getSuperior public AttributeType getSuperior() Returns: AttributeType representing the oid of an attribute type from which this attribute is derived. Since this field is optional, this method may return null. 5.1.13 setSuperior public void setSuperior(AttributeType superior) Parameters: superior - AttributeType of an attribute type from which this attribute is derived. 5.1.14 getEquality Expires 8/99 [Page 109] JAVA LDAP API February 1999 public MatchingRuleId getEquality() Returns: an MatchingRuleId of the equality matching rule to use when evaluating attribute values for selection. Since this field is optional, this method may return null. 5.1.15 setEquality public void setEquality(MatchingRuleId equality) Parameters: equality - a MatchingRuleId of the equality matching rule to use when evaluating attribute values for selection. 5.1.16 getOrdering public MatchingRuleId getOrdering() Returns: a MatchingRuleId of the ordering matching rule to use when evaluating attribute values for selection. Since this field is optional, this method may return null. 5.1.17 setOrdering public void setOrdering(MatchingRuleId ordering) Returns: an MatchingRuleId of the ordering matching rule to use when evaluating attribute values for selection. 5.1.18 getSubstr public MatchingRuleId getSubstr() Returns: a MatchingRuleId of the substring matching rule to use when evaluating attribute values for selection. Since this field is optional, this method may return null. 5.1.19 setSubstr public void setSubstr(MatchingRuleId substr) Returns: a MatchingRuleId of the substring matching rule to use when evaluating attribute values for selection. Since this field is optional, this method may return null. 5.1.20 getSyntax public SyntaxId getSyntax() Returns: the SyntaxID representing the LDAP syntax used by this attribute. Since this field is optional, this method may return null. 5.1.21 setSyntax Expires 8/99 [Page 110] JAVA LDAP API February 1999 public void setSyntax(SyntaxId syntax) Parameters: syntax - the SyntaxID representing the LDAP syntax used by this attribute. 5.1.22 getSuggestedSyntaxLength public int getSuggestedSyntaxLength() Returns: int representing the suggested minimum upper bound on the number of characters in value with a string-based syntax, or the number of bytes in a value for all other syntaxes; -1 if there is no suggested length 5.1.23 setSuggestedSyntaxLength public void setSuggestedSyntaxLength(int length) Parameters: length - int representing the suggested minimum upper bound on the number of characters in value with a string-based syntax, or the number of bytes in a value for all other syntaxes; -1 if there is no suggested length 5.1.24 isSingleValue public boolean isSingleValue() Returns: true if this attribute can contain more than one value; false otherwise; default is false 5.1.25 setSingleValue public void setSingleValue(boolean isSingleValue) Parameters: isSingleValue - true if this attribute can contain more than one value; false otherwise; 5.1.26 isCollective public boolean isCollective() Returns: true if this attribute is collective; false otherwise; default is false; A collective attribute is one whose values are the same for each member of an entry collection. 5.1.27 setCollective public void setCollective(boolean isCollective) Parameters: Expires 8/99 [Page 111] JAVA LDAP API February 1999 isCollective - true if this attribute is collective; false otherwise; A collective attribute is one whose values are the same for each member of an entry collection. 5.1.28 isNoUserModification public boolean isNoUserModification() Returns: true if this attribute can modified by the directory user; false otherwise; default is false. 5.1.29 setNoUserModification public void setNoUserModification(boolean isNoUserModification) Parameters: isNoUserModification - true if this attribute can modified by the directory user; false otherwise. 5.1.30 getUsage public AttributeUsage getUsage() Returns: a Usage representing the intended use of this attribute 5.2 Class org.ietf.ldap.schema.AttributeUsage public final class AttributeUsage Provides an enumeration of usage values for an AttributeDefinition. 5.2.1 Fields public static final AttributeUsage USER_APPLICATIONS public static final AttributeUsage DIRECTORY_OPERATIONS public static final AttributeUsage DISTRIBUTED_OPERATIONS public static final AttributeUsage DSA_OPERATIONS 5.2.2 fromString public static AttributeUsage fromString(String usageString) Parameters: usageString - String representing a valid usage string; should be one for the following: userApplications directoryOperation distributedOperation dSAOperation Returns: an AttributeUsage corresponding to a string value; null if Expires 8/99 [Page 112] JAVA LDAP API February 1999 input String is not one of the valid usage strings 5.3 Class org.ietf.ldap.schema.MatchingRuleDefinition public class MatchingRuleDefinition extends SchemaDefinition MatchingRuleDefinition represents the Matching Rule as part of an LDAP schema defined in section 4.2 of RFC 2252. A matching rule allows a set of entries in a DIB to be selected by making particular assertions concerning their attribute values. 5.3.1 Fields public static final String TYPE 5.3.2 Constructors public MatchingRuleDefinition(String value) throws ProtocolException Constructs an instance from a String containing terminal symbols and variables as specified in section 4.2 of RFC 2252. Parameters: value - the String containing information to be parsed Throws: ProtocolException - If there is a problem with the data in value public MatchingRuleDefinition(MatchingRuleId oid, SyntaxId syntax) Parameters: oid - MatchingRuleId representing the oid of this rule syntax - SyntaxId representing the oid of the syntax used by this rule 5.3.3 toAttribute public Attribute toAttribute() Returns: an Attribute which contains the type and value of this definition 5.3.4 getOid public MatchingRuleId getOid() Returns: the MatchingRuleId representing the oid of the rule defined here 5.3.5 getNames public String[] getNames() Expires 8/99 [Page 113] JAVA LDAP API February 1999 Returns: an array of Strings representing the names by which this rule is known. Since this field is optional, this method may return null. 5.3.6 setNames public void setNames(String[] names) Parameters: names - an array of Strings representing the names by which this rule is known. 5.3.7 getDescription public String getDescription() Returns: a String representing a verbose description of this rule. Since this field is optional, this method may return null. 5.3.8 setDescription public void setDescription(String description) Parameters: description - a String representing a verbose description of this rule. 5.3.9 isObsolete public boolean isObsolete() Returns: true if this rule is being phased out; false otherwise; default is false 5.3.10 setObsolete public void setObsolete(boolean isObsolete) Parameters: isObsolete - true if this rule is being phased out; false otherwise 5.3.11 getSyntax public SyntaxId getSyntax() Returns: OID of the syntax used to express an assertion of each specific type of match 5.3.12 setSyntax public void setSyntax(SyntaxId syntax) Parameters: syntax - the SyntaxID representing the LDAP syntax used by this rule Expires 8/99 [Page 114] JAVA LDAP API February 1999 5.4 Class org.ietf.ldap.schema.ObjectClassDefinition public class ObjectClassDefinition extends SchemaDefinition ObjectClassDefinition represents the Object Class as part of an LDAP schema defined in section 4.2 of RFC 2252. Object class definitions define the basic set of mandatory and optional attributes that shall be present, and may be present, respectively, in an entry of a give class, and which indicate the kind of object class that is being defined. 5.4.1 Fields public static final String TYPE 5.4.2 Constructors public ObjectClassDefinition(String value) throws ProtocolException Constructs an instance from a String containing terminal symbols and variables as specified in section 4.2 of RFC 2252. Parameters: value - the String containing information to be parsed Throws: ProtocolException - If there is a problem with the data in value public ObjectClassDefinition(ObjectClassId oid) Parameters: oid - ObjectClassId representing the oid of this class 5.4.3 toAttribute public Attribute toAttribute() Returns: an Attribute which contains the type and value of this definition 5.4.4 getOid public ObjectClassId getOid() Returns: the ObjectClassId of the object class defined here 5.4.5 getNames public String[] getNames() Returns: an array of Strings representing the names by which this object class is known Since this field is optional, this method may Expires 8/99 [Page 115] JAVA LDAP API February 1999 return null. 5.4.6 setNames public void setNames(String[] names) Parameters: names - an array of Strings representing the names by which this class is known. 5.4.7 getDescription public String getDescription() Returns: a String representing a verbose description of this class. Since this field is optional, this method may return null. 5.4.8 setDescription public void setDescription(String description) Parameters: description - a String representing a verbose description of this class. 5.4.9 isObsolete public boolean isObsolete() Returns: true if this object class is being phased out; false otherwise; default is false 5.4.10 setObsolete public void setObsolete(boolean isObsolete) Parameters: isObsolete - true if this class is being phased out; false otherwise; 5.4.11 getSuperiors public ObjectClassId[] getSuperiors() Returns: an array of ObjectClassIds representing the oids of classes from which this object class is derived. Since this field is optional, this method may return null. 5.4.12 setSuperiors public void setSuperiors(ObjectClassId[] superiors) Parameters: superior - ObjectClassIds representing the oids of classes from which this object class is derived. Expires 8/99 [Page 116] JAVA LDAP API February 1999 5.4.13 getObjectClassType public ObjectClassType getObjectClassType() Returns: an ObjectClassType representing the kind of object class represented 5.4.14 setObjectClassType public void setObjectClassType(ObjectClassType type) Parameters: type - an ObjectClassType representing the kind of object class represented 5.4.15 getMusts public AttributeType[] getMusts() Returns: an array of AttributeTypes representing the oids of mandatory attribute types an entry of the object class shall contain in addition to the mandatory attribute types of all its superiors. Since this field is optional, this method may return null. 5.4.16 setMusts public void setMusts(AttributeType[] musts) Parameters: musts - an array of AttributeTypes representing the oids of mandatory attribute types an entry of the object class shall contain in addition to the mandatory attribute types of all its superiors. 5.4.17 getMays public AttributeType[] getMays() Returns: an array of AttributeTypes representing the oids of optional attribute types an entry of the object class may contain in addition to the optional attribute types of all its superiors. Since this field is optional, this method may return null. 5.4.18 setMays public void setMays(AttributeType[] mays) Parameters: musts - an array of AttributeTypes representing the oids of optional attribute types an entry of the object class may contain in addition to the mandatory attribute types of all its superiors. 5.5 Class org.ietf.ldap.schema.ObjectClassId Expires 8/99 [Page 117] JAVA LDAP API February 1999 public class ObjectClassId extends SchemaElementId The ObjectClassId represents the OID and/or name by which a given ObjectClass is known. If both a name and OID are present in an instance of ObjectClassId then the instance can considered to assign the name to the OID in the context of a specific type of server. 5.5.1 Constructors public ObjectClassId(OID oid) public ObjectClassId(String name) public ObjectClassId(OID oid, String name) 5.6 Class org.ietf.ldap.schema.ObjectClassType public final class ObjectClassType Provides an enumeration of types of object classes specified in ObjectClassDefinition. 5.6.1 Fields public static final ObjectClassType ABSTRACT public static final ObjectClassType STRUCTURAL public static final ObjectClassType AUXILIARY 5.6.2 fromString public static ObjectClassType fromString(String typeString) Parameters: typeString - String representing a valid type; should be one for the following: ABSTRACT STRUCTURAL AUXILIARY Returns: an ObjectClassType corresponding to a string value; null if input String is not one of the valid type strings 5.7 Class org.ietf.ldap.schema.Schema public class Schema Schema is the collection of attribute type definitions, object class definitions and other information which a server uses to determine how to match a filter or attribute value assertions (in a compare operation) against the attributes of an entry, and whether to permit add and modify operations. Schema is defined formally in RFC 2252. Expires 8/99 [Page 118] JAVA LDAP API February 1999 5.7.1 Constructors public Schema(Entry entry) throws ProtocolException Constructs an instance from an LDAP directory entry, assumed to be a subschema entry referred to in the root DS entry attribute "subschemaentry". Parameters: entry - Entry assumed to contain schema information Throws: ProtocolException - If there is a problem parsing the information in the entry. public Schema(SchemaDefinition[] defArray) Parameters: defArray - an array of SchemaDefinition objects which to store in this Schema 5.7.2 toAttributeSet public AttributeSet toAttributeSet() Returns: an AttributeSet that contains the attributes of this schema 5.7.3 toEntry public Entry toEntry(DN dn) Parameters: dn - DN of the new entry Returns: an Entry containing this schema, suitable for placement in the directory 5.7.4 addDefinition public void addDefinition(SchemaDefinition definition) Adds a SchemaDefinition to the Schema. Parameters: definition - SchemaDefinition to add 5.7.5 getAttributeTypes public AttributeDefinition[] getAttributeTypes() Returns: an array of all SchemaDefinitions stored here which are subclassed as AttributeDefinition Expires 8/99 [Page 119] JAVA LDAP API February 1999 5.7.6 getObjectClasses public ObjectClassDefinition[] getObjectClasses() Returns: an array of all SchemaDefinitions stored here which are subclassed as ObjectClassDefinition 5.7.7 getSyntaxes public SyntaxDefinition[] getSyntaxes() Returns: an array of all SchemaDefinitions stored here which are subclassed as SyntaxDefinition 5.7.8 getMatchingRules public MatchingRuleDefinition[] getMatchingRules() Returns: an array of all SchemaDefinitions stored here which are subclassed as MatchingRuleDefinition 5.7.9 getSchemaDescriptions public SchemaDescriptionDefinition[] getSchemaDescriptions() Returns: an array of all SchemaDefinitions stored here which are subclassed as SchemaDescriptionDefinition 5.8 Class org.ietf.ldap.schema.SchemaDefinition Subclasses: AttributeDefinition, MatchingRuleDefinition, ObjectClassDefinition, SchemaDescriptionDefinition, SyntaxDefinition public abstract class SchemaDefinition SchemaDefinition represents a definition found in an LDAP schema as defined in RFC 2252. 5.8.1 Constructors public SchemaDefinition() 5.8.2 toAttribute public abstract Attribute toAttribute() Returns: an Attribute which contains the type and value of this definition 5.9 Class org.ietf.ldap.schema.SchemaDescriptionDefinition public class SchemaDescriptionDefinition Expires 8/99 [Page 120] JAVA LDAP API February 1999 extends SchemaDefinition SchemaDescriptionDefinition represents the Attribute Types as part of an LDAP schema defined in draft-ietf-schema-ldap-00 Each value of the LDAP schema definition defines one schema and contains the elements needed for an LDAPv3 server to correctly process operations which use its definitions. The "NAME" field contains optional human-readable labels for the schema. The "OBSOLETE" field is present if the schema is obsolete. The "IMPORTS" field lists the OIDs of other schemas which are to be incorporated by reference into this schema. It is an error to have an attribute type or object class defined in a schema with the same name but a different OID as an attribute type or object class in an imported schema. It is also an error to import from two schema definitions in which there are attribute types or object classes with the same names but different OIDs. The "CLASSES" field lists the OIDs of object classes defined in this schema. A schema need not contain any object class definitions. A schema must not contain two object class definitions of the same name but with different OIDs. The "ATTRIBUTES" field lists the OIDs of attribute types defined in this schema. A schema need not contain any object class definitions. A schema must not contain two attribute type definitions of the same name but with different OIDs. The "MATCHING- RULES" field lists the OIDs of matching rules defined in this schema. A schema need not contain any matching rules. The "SYNTAXES" field lists the OIDs of syntaxes defined in this schema. A schema need not contain any syntaxes. 5.9.1 Fields public static final String TYPE 5.9.2 Constructors SchemaDescriptionDefinition public SchemaDescriptionDefinition(String value) throws ProtocolException Constructs an instance from a String containing terminal symbols and variables as specified in draft-ietf-schema- ldap-00. Parameters: value - the String containing information to be parsed Throws: ProtocolException - If there is a problem with the data in value 5.9.3 SchemaDescriptionDefinition public SchemaDescriptionDefinition(SchemaDescriptionId oid) Expires 8/99 [Page 121] JAVA LDAP API February 1999 Parameters: oid - SchemaDescriptionId representing the oid of this schema 5.9.4 toAttribute public Attribute toAttribute() Returns: an Attribute which contains the type and value of this definition 5.9.5 getOid public SchemaDescriptionId getOid() Returns: the SchemaDescriptionId representing the oid of the schema defined here 5.9.6 getNames public String[] getNames() Returns: an array of Strings representing the names by which this schema is known. Since this field is optional, this method may return null. 5.9.7 setNames public void setNames(String[] names) Parameters: names - an array of Strings representing the names by which this schema is known. 5.9.8 isObsolete public boolean isObsolete() Returns: true if this attribute is being phased out; false otherwise; default is false 5.9.9 setObsolete public void setObsolete(boolean isObsolete) Parameters: isObsolete - true if this schema is being phased out; false otherwise; 5.9.10 getImports public SchemaDescriptionId[] getImports() Returns: an array of SchemaDescriptionIds of other LDAP schemas Expires 8/99 [Page 122] JAVA LDAP API February 1999 included by reference into this schema. Since this field is optional, this method may return null. 5.9.11 setImports public void setImports(SchemaDescriptionId[] imports) Parameters: imports - return an array of SchemaDescriptionIds of other LDAP schemas included by reference into this schema. 5.9.12 getClasses public ObjectClassId[] getClasses() Returns: an array of ObjectClassIds representing the oids of object classes included in in this LDAP schema. Since this field is optional, this method may return null. 5.9.13 setClasses public void setClasses(ObjectClassId[] classes) Parameters: classes - an array of ObjectClassIds representing the oids of object classes included in in this LDAP schema. 5.9.14 getAttributes public AttributeType[] getAttributes() Returns: an array of AttributeTypes of attributes included in this LDAP schema. Since this field is optional, this method may return null. 5.9.15 setAttributes public void setAttributes(AttributeType[] attributes) Parameters: attributes - an array of AttributeTypes of attributes included in this LDAP schema. 5.9.16 getMatchingRules public MatchingRuleId[] getMatchingRules() Returns: an array of MatchingRuleIds representing the oids of matching rules included in this LDAP schema. Since this field is optional, this method may return null. 5.9.17 setMatchingRules public void setMatchingRules(MatchingRuleId[] rules) Expires 8/99 [Page 123] JAVA LDAP API February 1999 Parameters: rules - an array of MatchingRuleIds representing the oids of matching rules included in this LDAP schema. 5.9.18 getSyntaxes public SyntaxId[] getSyntaxes() Returns: an array of SyntaxIds representing the oids of syntaxes included in this LDAP schema. Since this field is optional, this method may return null. 5.9.19 setSyntaxes public void setSyntaxes(SyntaxId[] syntaxes) Parameters: syntaxes - an array of SyntaxIds representing the oids of syntaxes included in this LDAP schema. 5.10 Class org.ietf.ldap.schema.SchemaDescriptionId public class SchemaDescriptionId extends SchemaElementId The SchemaDescriptionId represents the OID and/or name by which a given SchemaDescription is known. If both a name and OID are present in an instance of SchemaDescriptionId then the instance can be considered to assign the name to the OID in the context of a specific type of server. 5.10.1 Constructors public SchemaDescriptionId(OID oid) public SchemaDescriptionId(String name) public SchemaDescriptionId(OID oid, String name) 5.11 Class org.ietf.ldap.schema.SyntaxDefinition public class SyntaxDefinition extends SchemaDefinition SyntaxDefinition represents the Syntax as part of an LDAP schema defined in section 4.2 of RFC 2252. A syntax defines what kind of information is allowed to be stored in an attribute's values and how those values behave during searches and other directory operations. 5.11.1 Fields public static final String TYPE 5.11.2 Constructors Expires 8/99 [Page 124] JAVA LDAP API February 1999 public SyntaxDefinition(String value) throws ProtocolException Constructs an instance from a String containing terminal symbols and variables as specified in section 4.2 of RFC 2252. Parameters: value - the String containing information to be parsed Throws: ProtocolException - If there is a problem with the data in value SyntaxDefinition public SyntaxDefinition(SyntaxId oid) Constructs an instance from specified parameters Parameters: oid - SyntaxId representing the oid of this syntax 5.11.3 toAttribute public Attribute toAttribute() Returns: an Attribute which contains the type and value of this definition 5.11.4 getOid public SyntaxId getOid() Returns: the SyntaxId of the syntax defined here 5.11.5 getDescription public String getDescription() Returns: a String representing a verbose description of this syntax. Since this field is optional, this method may return null. 5.11.6 setDescription public void setDescription(String description) Parameters: return - a String representing a verbose description of this syntax. 5.12 Class org.ietf.ldap.schema.SyntaxId public class SyntaxId extends SchemaElementId The SyntaxId represents the OID and/or name by which a given Syntax is Expires 8/99 [Page 125] JAVA LDAP API February 1999 known. If both a name and OID are present in an instance of SyntaxId then the instance can considered to assign the name to the OID in the context of a specific type of server. NOTE: the use of a name to describe a syntax ID is not provided for in the specification defined in RFC 2252. This ability is included here for use with directory servers not conforming to the specification. 5.12.1 Constructors public SyntaxId(OID oid) public SyntaxId(String name) public SyntaxId(OID oid, String name) 5.13 Class org.ietf.ldap.schema.SyntaxTable public class SyntaxTable Provides routines for converting syntax oids to descriptions and vice versa. Lookups are based on the contents of file syntax.properties in this package and if defined, the contents of syntax.properties in the directory of the program using this class. In this way syntaxes can be extended by the user. The contents of syntax.properties contains on one syntax oid-name combination per line in the form =. 5.13.1 getDescription public static String getDescription(OID oid) Retrieves a description given an OID. Parameters: oid - OID of a syntax Returns: String representing the description of the OID 5.13.2 getOid public static OID getOid(String description) Retrieves an OID given a description. Parameters: description - String representing the description of the OID Returns: oid OID of a syntax 6. Security Considerations LDAP supports security through protocol-level authentication, using clear-text passwords or other more secure mechanisms. It also supports running over TLS, which provides strong security at the transport layer. This draft supports TLS implementations, via the Expires 8/99 [Page 126] JAVA LDAP API February 1999 SocketHandler interface. 7. Full Copyright Statement Copyright (C) The Internet Society (1999). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implmentation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 8. Bibliography [1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation X.520. [2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory Access Protocol: Standard and Pilot Attribute Definitions", RFC 2256. [3] T. Howes, "A String Representation of LDAP Search Filters," RFC 2254. [4] M. Wahl, S. Kille, T. Howes, "A String Representation of Distinguished Names," RFC 2253. [5] T. Howes, M. Smith, "An LDAP URL Format", RFC 2255. [6] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol", RFC 2251. [7] M. Wahl, T. Howes, "Use of Language Codes in LDAPv3", Internet Draft draft-ietf-asid-ldapv3-lang-02.txt, June 1997. [8] C. Tomlinson, K. Sutter, M. Wahl, "org.ietf.ldap.controls package for the Java(tm) LDAP API", Internet Draft draft-ietf-ldapext-alt- java-controls-00.txt. Expires 8/99 [Page 127] JAVA LDAP API February 1999 [9] C. Tomlinson, K. Sutter, M. Wahl, "org.ietf.ldap.apdu package for the Java(tm) LDAP API", Internet Draft draft-ietf-ldapext-alt-java -apdu-00.txt. [10] R. Weltman, T. Howes, M. Smith, C. Ho, " The Java LDAP Application Program Interface", draft-ietf-ldapext-ldap-java-api-03.txt 9. Author's Addresses Christine Tomlinson Innosoft International, Inc. 8911 Capital of Texas Highway Suite 4140 Austin, TX US 78759 +1 512 231 1600 christine.tomlinson@innosoft.com Mark Wahl Innosoft International, Inc. 8911 Capital of Texas Highway Suite 4140 Austin, TX US 78759 +1 512 231 1600 mark.wahl@innosoft.com APPENDIX Example Although there are quite a few classes in the org.ietf.ldap.* packages, relatively few of them are essential for getting started with LDAP. Thus, it is best to take a top down approach in learning the package, starting with the DirectoryClient. After creating this object, interaction with the server is performed by calling methods on this object that correspond to the requests of the LDAP protocol in RFC 2251. The following example is adapted from Appendix A of RFC 1823 - The C LDAP API and should illustrate the main points of the Java version of the API: import org.ietf.ldap.*; import org.ietf.ldap.client.*; import java.util.*; public class SimpleSearch { public static void main(String[] args) { if (args.length < 4) { System.err.println( "Usage: java SimpleSearch "); System.exit(1); } try { /* open an LDAP session */ Expires 8/99 [Page 128] JAVA LDAP API February 1999 DirectoryClient client = new DirectoryClient(args[0], Integer.parseInt(args[1])); /* authenticate as nobody */ client.bind(null, null); /* search for entries rooted at dn matching filter, return all attrs */ String dn = args[2]; String filter = args[3]; SearchResults results = client.search(dn, Scope.SUBTREE, filter, null, false); /* step through each entry returned */ while (results.hasMoreElements()) { Entry entry = results.next(); /* print its name */ System.out.println("dn: " + entry.getDN()); Enumeration enum = entry.getAttributes().elements(); /* print each attribute */ while (enum.hasMoreElements()) { Attribute attr = (Attribute)enum.nextElement(); System.out.println("attribute: " + attr.getDescription()); AttributeValue[] values = attr.getValues(); /* print each value */ for (int i = 0; i < values.length; i++) System.out.println(" value: " + values[i]); } } /* close the LDAP session */ client.unbind(); } catch (Exception ex) { ex.printStackTrace(); } } } Running the program as follows: java SimpleSearch thundercloud 389 "dc=ietf,dc=org" "cn=Thomas Mann" might give output similar to: dn: cn=Thomas Mann,dc=ietf,dc=org attribute: cn value: Thomas Mann attribute: sn value: Mann attribute: telephonenumber value: 555-1234 attribute: objectclass value: top value: person attribute: createtimestamp value: 19980528221642Z attribute: creatorsname value: cn=manager,dc=ietf,dc=org Expires 8/99 [Page 129] JAVA LDAP API February 1999 attribute: description value: writer of some repute attribute: modifytimestamp value: 19980812153340Z attribute: modifiersname value: cn=manager For general asynchronous support see ClientConnection and Interaction. These classes support applications that pipeline requests to single servers and process concurrent requests across multiple servers. The Interaction will merge results from multiple requests, while the ClientConnection provides the basic non-blocking interface to submitting requests to a server. Expires 8/99 [Page 130]