APIdia Launch Partner
Top Description Fields Constructors Methods
javax.naming.ldap

public Class LdapName

extends Object
implements Name
Class Inheritance
All Implemented Interfaces
javax.naming.Name, java.lang.Comparable, java.io.Serializable, java.lang.Cloneable
Imports
javax.naming.Name, .InvalidNameException, java.util.Enumeration, .Collection, .ArrayList, .List, .Iterator, .ListIterator, .Collections, java.io.ObjectOutputStream, .ObjectInputStream, .IOException
This class represents a distinguished name as specified by RFC 2253. A distinguished name, or DN, is composed of an ordered list of components called relative distinguished names, or RDNs. Details of a DN's syntax are described in RFC 2253.

This class resolves a few ambiguities found in RFC 2253 as follows:

String names passed to LdapName or returned by it use the full Unicode character set. They may also contain characters encoded into UTF-8 with each octet represented by a three-character substring such as "\\B4". They may not, however, contain characters encoded into UTF-8 with each octet represented by a single character in the string: the meaning would be ambiguous.

LdapName will properly parse all valid names, but does not attempt to detect all possible violations when parsing invalid names. It is "generous" in accepting invalid names. The "validity" of a name is determined ultimately when it is supplied to an LDAP server, which may accept or reject the name based on factors such as its schema information and interoperability considerations.

When names are tested for equality, attribute types, both binary and string values, are case-insensitive. String values with different but equivalent usage of quoting, escaping, or UTF8-hex-encoding are considered equal. The order of components in multi-valued RDNs (such as "ou=Sales+cn=Bob") is not significant.

The components of a LDAP name, that is, RDNs, are numbered. The indexes of a LDAP name with n RDNs range from 0 to n-1. This range may be written as [0,n). The right most RDN is at index 0, and the left most RDN is at index n-1. For example, the distinguished name: "CN=Steve Kille, O=Isode Limited, C=GB" is numbered in the following sequence ranging from 0 to 2: {C=GB, O=Isode Limited, CN=Steve Kille}. An empty LDAP name is represented by an empty RDN list.

Concurrent multithreaded read-only access of an instance of LdapName need not be synchronized.

Unless otherwise noted, the behavior of passing a null argument to a constructor or method in this class will cause a NullPointerException to be thrown.

Author
Scott Seligman
Since
1.5

Field Summary

Modifier and TypeField and Description
private transient List<Rdn>
rdns

private static final long
serialVersionUID

Hides javax.naming.Name.serialVersionUID.

private transient String
unparsed

Constructor Summary

AccessConstructor and Description
public
LdapName(String
This is a non-null distinguished name formatted according to the rules defined in RFC 2253.
name)

Constructs an LDAP name from the given distinguished name.

public
LdapName(List<Rdn>
The non-null list of Rdns forming this LDAP name.
rdns)

Constructs an LDAP name given its parsed RDN components.

private
LdapName(String name, List<Rdn> rdns, int beg, int end)

Method Summary

Modifier and TypeMethod and Description
public Name

Returns:

The updated LdapName, not a new instance. Cannot be null.
add(String
The non-null component to add.
comp)

Implements javax.naming.Name.add.

Adds a single component to the end of this LDAP name.

public Name

Returns:

The updated LdapName, not a new instance. Cannot be null.
add(Rdn
The non-null RDN to add.
comp)

Adds a single RDN to the end of this LDAP name.

public Name

Returns:

The updated LdapName, not a new instance. Cannot be null.
add(int
The index at which to add the new component. Must be in the range [0,size()].
posn, String
The non-null component to add.
comp)

Implements javax.naming.Name.add.

Adds a single component at a specified position within this LDAP name.

public Name

Returns:

The updated LdapName, not a new instance. Cannot be null.
add(int
The index at which to add the new RDN. Must be in the range [0,size()].
posn, Rdn
The non-null RDN to add.
comp)

Adds a single RDN at a specified position within this LDAP name.

public Name

Returns:

The updated name (not a new instance).
addAll(Name
The non-null components to add.
suffix)

Implements javax.naming.Name.addAll.

Adds the components of a name -- in order -- to the end of this name.

public Name

Returns:

The updated name (not a new instance).
addAll(List<Rdn>
The non-null suffix Rdns to add.
suffixRdns)

Adds the RDNs of a name -- in order -- to the end of this name.

public Name

Returns:

The updated name (not a new instance).
addAll(int
The index at which to add the new component. Must be in the range [0,size()].
posn, Name
The non-null components to add.
suffix)

Implements javax.naming.Name.addAll.

Adds the components of a name -- in order -- at a specified position within this name.

public Name

Returns:

The updated name (not a new instance).
addAll(int
The index at which to add the suffix RDNs. Must be in the range [0,size()].
posn, List<Rdn>
The non-null suffix Rdns to add.
suffixRdns)

Adds the RDNs of a name -- in order -- at a specified position within this name.

public Object

Returns:

A copy of the this LDAP name.
clone()

Overrides java.lang.Object.clone.

Implements javax.naming.Name.clone.

Generates a new copy of this name.

public int

Returns:

A negative integer, zero, or a positive integer as this Name is less than, equal to, or greater than the given obj.
compareTo(Object
The non-null LdapName instance to compare against.
obj)

Implements javax.naming.Name.compareTo.

Compares this LdapName with the specified Object for order.

private boolean
doesListMatch(int beg, int end, List<Rdn> rdns)

public boolean

Returns:

true if n is a suffix of this name, false otherwise.
endsWith(Name
The LDAP name to check.
n)

Implements javax.naming.Name.endsWith.

Determines whether this LDAP name ends with a specified LDAP name suffix.

public boolean

Returns:

true if rdns form a suffix of this LDAP name, false otherwise.
endsWith(List<Rdn>
The sequence of Rdns to check.
rdns)

Determines whether the specified RDN sequence forms a suffix of this LDAP name.

public boolean

Returns:

true if obj is equal to this LDAP name, false otherwise.
equals(Object
The possibly null object to compare against.
obj)

Overrides java.lang.Object.equals.

Determines whether two LDAP names are equal.

public String

Returns:

The non-null component at index posn.
get(int
The 0-based index of the component to retrieve. Must be in the range [0,size()).
posn)

Implements javax.naming.Name.get.

Retrieves a component of this LDAP name as a string.

public Enumeration<String>

Returns:

A non-null enumeration of the components of this LDAP name. Each element of the enumeration is of class String.
getAll()

Implements javax.naming.Name.getAll.

Retrieves the components of this name as an enumeration of strings.

public Name

Returns:

An instance of LdapName consisting of the components at indexes in the range [0,posn). If posn is zero, an empty LDAP name is returned.
getPrefix(int
The 0-based index of the component at which to stop. Must be in the range [0,size()].
posn)

Implements javax.naming.Name.getPrefix.

Creates a name whose components consist of a prefix of the components of this LDAP name.

public Rdn

Returns:

The non-null RDN at index posn.
getRdn(int
The 0-based index of the RDN to retrieve. Must be in the range [0,size()).
posn)

Retrieves an RDN of this LDAP name as an Rdn.

public List<Rdn>

Returns:

The name as a list of RDNs which are instances of the class Rdn.
getRdns()

Retrieves the list of relative distinguished names.

public Name

Returns:

An instance of LdapName consisting of the components at indexes in the range [posn,size()). If posn is equal to size(), an empty LDAP name is returned.
getSuffix(int
The 0-based index of the component at which to start. Must be in the range [0,size()].
posn)

Implements javax.naming.Name.getSuffix.

Creates a name whose components consist of a suffix of the components in this LDAP name.

public int

Returns:

An int representing the hash code of this name.
hashCode()

Overrides java.lang.Object.hashCode.

Computes the hash code of this LDAP name.

public boolean

Returns:

true if this LDAP name is empty, false otherwise.
isEmpty()

Implements javax.naming.Name.isEmpty.

Determines whether this LDAP name is empty.

private boolean
matches(int beg, int end, Name n)

private void
parse()

private void
readObject(ObjectInputStream
the ObjectInputStream to read from
s)

The readObject method is called to restore the state of the LdapName from a stream.

public Object

Returns:

The component removed (a String).
remove(int
The index of the component to remove. Must be in the range [0,size()).
posn)

Implements javax.naming.Name.remove.

Removes a component from this LDAP name.

public int

Returns:

The non-negative number of components in this LDAP name.
size()

Implements javax.naming.Name.size.

Retrieves the number of components in this LDAP name.

public boolean

Returns:

true if n is a prefix of this LDAP name, false otherwise.
startsWith(Name
The LDAP name to check.
n)

Implements javax.naming.Name.startsWith.

Determines whether this LDAP name starts with a specified LDAP name prefix.

public boolean

Returns:

true if rdns form a prefix of this LDAP name, false otherwise.
startsWith(List<Rdn>
The sequence of Rdns to check.
rdns)

Determines whether the specified RDN sequence forms a prefix of this LDAP name.

public String

Returns:

The string representation of the LdapName.
toString()

Overrides java.lang.Object.toString.

Returns a string representation of this LDAP name in a format defined by RFC 2253 and described in the class description.

private void
writeObject(ObjectOutputStream
the ObjectOutputStream to write to
s)

The writeObject method is called to save the state of the LdapName to a stream.

Inherited from java.lang.Object:
finalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

rdnsback to summary
private transient List<Rdn> rdns
serialVersionUIDback to summary
private static final long serialVersionUID

Hides javax.naming.Name.serialVersionUID.

Annotations
@Serial
unparsedback to summary
private transient String unparsed

Constructor Detail

LdapNameback to summary
public LdapName(String name) throws InvalidNameException

Constructs an LDAP name from the given distinguished name.

Parameters
name:String

This is a non-null distinguished name formatted according to the rules defined in RFC 2253.

Exceptions
InvalidNameException:
if a syntax violation is detected.
See Also
Rdn#escapeValue(Object value)
LdapNameback to summary
public LdapName(List<Rdn> rdns)

Constructs an LDAP name given its parsed RDN components.

The indexing of RDNs in the list follows the numbering of RDNs described in the class description.

Parameters
rdns:List<Rdn>

The non-null list of Rdns forming this LDAP name.

LdapNameback to summary
private LdapName(String name, List<Rdn> rdns, int beg, int end)

Method Detail

addback to summary
public Name add(String comp) throws InvalidNameException

Implements javax.naming.Name.add.

Adds a single component to the end of this LDAP name.

Parameters
comp:String

The non-null component to add.

Returns:Name

The updated LdapName, not a new instance. Cannot be null.

Exceptions
InvalidNameException:
If adding comp at end of the name would violate the name's syntax.
addback to summary
public Name add(Rdn comp)

Adds a single RDN to the end of this LDAP name.

Parameters
comp:Rdn

The non-null RDN to add.

Returns:Name

The updated LdapName, not a new instance. Cannot be null.

addback to summary
public Name add(int posn, String comp) throws InvalidNameException

Implements javax.naming.Name.add.

Adds a single component at a specified position within this LDAP name. Components of this LDAP name at or after the index (if any) of the new component are shifted up by one (away from index 0) to accommodate the new component.

Parameters
posn:int

The index at which to add the new component. Must be in the range [0,size()].

comp:String

The non-null component to add.

Returns:Name

The updated LdapName, not a new instance. Cannot be null.

Exceptions
InvalidNameException:
If adding comp at the specified position would violate the name's syntax.
IndexOutOfBoundsException:
If posn is outside the specified range.
addback to summary
public Name add(int posn, Rdn comp)

Adds a single RDN at a specified position within this LDAP name. RDNs of this LDAP name at or after the index (if any) of the new RDN are shifted up by one (away from index 0) to accommodate the new RDN.

Parameters
posn:int

The index at which to add the new RDN. Must be in the range [0,size()].

comp:Rdn

The non-null RDN to add.

Returns:Name

The updated LdapName, not a new instance. Cannot be null.

Exceptions
IndexOutOfBoundsException:
If posn is outside the specified range.
addAllback to summary
public Name addAll(Name suffix) throws InvalidNameException

Implements javax.naming.Name.addAll.

Adds the components of a name -- in order -- to the end of this name.

Parameters
suffix:Name

The non-null components to add.

Returns:Name

The updated name (not a new instance).

Exceptions
InvalidNameException:
if suffix is not a valid LDAP name, or if the addition of the components would violate the syntax rules of this LDAP name.
addAllback to summary
public Name addAll(List<Rdn> suffixRdns)

Adds the RDNs of a name -- in order -- to the end of this name.

Parameters
suffixRdns:List<Rdn>

The non-null suffix Rdns to add.

Returns:Name

The updated name (not a new instance).

addAllback to summary
public Name addAll(int posn, Name suffix) throws InvalidNameException

Implements javax.naming.Name.addAll.

Adds the components of a name -- in order -- at a specified position within this name. Components of this LDAP name at or after the index (if any) of the first new component are shifted up (away from index 0) to accommodate the new components.

Parameters
posn:int

The index at which to add the new component. Must be in the range [0,size()].

suffix:Name

The non-null components to add.

Returns:Name

The updated name (not a new instance).

Exceptions
InvalidNameException:
if suffix is not a valid LDAP name, or if the addition of the components would violate the syntax rules of this LDAP name.
IndexOutOfBoundsException:
If posn is outside the specified range.
addAllback to summary
public Name addAll(int posn, List<Rdn> suffixRdns)

Adds the RDNs of a name -- in order -- at a specified position within this name. RDNs of this LDAP name at or after the index (if any) of the first new RDN are shifted up (away from index 0) to accommodate the new RDNs.

Parameters
posn:int

The index at which to add the suffix RDNs. Must be in the range [0,size()].

suffixRdns:List<Rdn>

The non-null suffix Rdns to add.

Returns:Name

The updated name (not a new instance).

Exceptions
IndexOutOfBoundsException:
If posn is outside the specified range.
cloneback to summary
public Object clone()

Overrides java.lang.Object.clone.

Implements javax.naming.Name.clone.

Generates a new copy of this name. Subsequent changes to the components of this name will not affect the new copy, and vice versa.

Returns:Object

A copy of the this LDAP name.

compareToback to summary
public int compareTo(Object obj)

Implements javax.naming.Name.compareTo.

Compares this LdapName with the specified Object for order. Returns a negative integer, zero, or a positive integer as this Name is less than, equal to, or greater than the given Object.

If obj is null or not an instance of LdapName, ClassCastException is thrown.

Ordering of LDAP names follows the lexicographical rules for string comparison, with the extension that this applies to all the RDNs in the LDAP name. All the RDNs are lined up in their specified order and compared lexicographically. See Rdn.compareTo(Object obj) for RDN comparison rules.

If this LDAP name is lexicographically lesser than obj, a negative number is returned. If this LDAP name is lexicographically greater than obj, a positive number is returned.

Parameters
obj:Object

The non-null LdapName instance to compare against.

Returns:int

A negative integer, zero, or a positive integer as this Name is less than, equal to, or greater than the given obj.

Exceptions
ClassCastException:
if obj is null or not a LdapName.
doesListMatchback to summary
private boolean doesListMatch(int beg, int end, List<Rdn> rdns)
endsWithback to summary
public boolean endsWith(Name n)

Implements javax.naming.Name.endsWith.

Determines whether this LDAP name ends with a specified LDAP name suffix. A name n is a suffix if it is equal to getSuffix(size()-n.size())--in other words this LDAP name ends with 'n'. If n is null or not a RFC2253 formatted name as described in the class description, false is returned.

Parameters
n:Name

The LDAP name to check.

Returns:boolean

true if n is a suffix of this name, false otherwise.

See Also
getSuffix(int posn)
endsWithback to summary
public boolean endsWith(List<Rdn> rdns)

Determines whether the specified RDN sequence forms a suffix of this LDAP name. Returns true if this LdapName is at least as long as rdns, and for every position p in the range [size() - rdns.size(), size()) the component getRdn(p) matches rdns.get(p). Returns false otherwise. If rdns is null, false is returned.

Parameters
rdns:List<Rdn>

The sequence of Rdns to check.

Returns:boolean

true if rdns form a suffix of this LDAP name, false otherwise.

equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Determines whether two LDAP names are equal. If obj is null or not an LDAP name, false is returned.

Two LDAP names are equal if each RDN in one is equal to the corresponding RDN in the other. This implies both have the same number of RDNs, and each RDN's equals() test against the corresponding RDN in the other name returns true. See Rdn#equals(Object obj) for a definition of RDN equality.

Parameters
obj:Object

The possibly null object to compare against.

Returns:boolean

true if obj is equal to this LDAP name, false otherwise.

See Also
hashCode
getback to summary
public String get(int posn)

Implements javax.naming.Name.get.

Retrieves a component of this LDAP name as a string.

Parameters
posn:int

The 0-based index of the component to retrieve. Must be in the range [0,size()).

Returns:String

The non-null component at index posn.

Exceptions
IndexOutOfBoundsException:
if posn is outside the specified range.
getAllback to summary
public Enumeration<String> getAll()

Implements javax.naming.Name.getAll.

Retrieves the components of this name as an enumeration of strings. The effect of updates to this name on this enumeration is undefined. If the name has zero components, an empty (non-null) enumeration is returned. The order of the components returned by the enumeration is same as the order in which the components are numbered as described in the class description.

Returns:Enumeration<String>

A non-null enumeration of the components of this LDAP name. Each element of the enumeration is of class String.

getPrefixback to summary
public Name getPrefix(int posn)

Implements javax.naming.Name.getPrefix.

Creates a name whose components consist of a prefix of the components of this LDAP name. Subsequent changes to this name will not affect the name that is returned and vice versa.

Parameters
posn:int

The 0-based index of the component at which to stop. Must be in the range [0,size()].

Returns:Name

An instance of LdapName consisting of the components at indexes in the range [0,posn). If posn is zero, an empty LDAP name is returned.

Exceptions
IndexOutOfBoundsException:
If posn is outside the specified range.
getRdnback to summary
public Rdn getRdn(int posn)

Retrieves an RDN of this LDAP name as an Rdn.

Parameters
posn:int

The 0-based index of the RDN to retrieve. Must be in the range [0,size()).

Returns:Rdn

The non-null RDN at index posn.

Exceptions
IndexOutOfBoundsException:
if posn is outside the specified range.
getRdnsback to summary
public List<Rdn> getRdns()

Retrieves the list of relative distinguished names. The contents of the list are unmodifiable. The indexing of RDNs in the returned list follows the numbering of RDNs as described in the class description. If the name has zero components, an empty list is returned.

Returns:List<Rdn>

The name as a list of RDNs which are instances of the class Rdn.

getSuffixback to summary
public Name getSuffix(int posn)

Implements javax.naming.Name.getSuffix.

Creates a name whose components consist of a suffix of the components in this LDAP name. Subsequent changes to this name do not affect the name that is returned and vice versa.

Parameters
posn:int

The 0-based index of the component at which to start. Must be in the range [0,size()].

Returns:Name

An instance of LdapName consisting of the components at indexes in the range [posn,size()). If posn is equal to size(), an empty LDAP name is returned.

Exceptions
IndexOutOfBoundsException:
If posn is outside the specified range.
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Computes the hash code of this LDAP name. The hash code is the sum of the hash codes of individual RDNs of this name.

Returns:int

An int representing the hash code of this name.

See Also
equals
isEmptyback to summary
public boolean isEmpty()

Implements javax.naming.Name.isEmpty.

Determines whether this LDAP name is empty. An empty name is one with zero components.

Returns:boolean

true if this LDAP name is empty, false otherwise.

matchesback to summary
private boolean matches(int beg, int end, Name n)
parseback to summary
private void parse() throws InvalidNameException
readObjectback to summary
private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException

The readObject method is called to restore the state of the LdapName from a stream. See writeObject for a description of the serial form.

Parameters
s:ObjectInputStream

the ObjectInputStream to read from

Annotations
@Serial
Exceptions
IOException:
if an I/O error occurs
ClassNotFoundException:
if the class of a serialized object could not be found
removeback to summary
public Object remove(int posn) throws InvalidNameException

Implements javax.naming.Name.remove.

Removes a component from this LDAP name. The component of this name at the specified position is removed. Components with indexes greater than this position (if any) are shifted down (toward index 0) by one.

Parameters
posn:int

The index of the component to remove. Must be in the range [0,size()).

Returns:Object

The component removed (a String).

Exceptions
InvalidNameException:
if deleting the component would violate the syntax rules of the name.
IndexOutOfBoundsException:
if posn is outside the specified range.
sizeback to summary
public int size()

Implements javax.naming.Name.size.

Retrieves the number of components in this LDAP name.

Returns:int

The non-negative number of components in this LDAP name.

startsWithback to summary
public boolean startsWith(Name n)

Implements javax.naming.Name.startsWith.

Determines whether this LDAP name starts with a specified LDAP name prefix. A name n is a prefix if it is equal to getPrefix(n.size())--in other words this LDAP name starts with 'n'. If n is null or not a RFC2253 formatted name as described in the class description, false is returned.

Parameters
n:Name

The LDAP name to check.

Returns:boolean

true if n is a prefix of this LDAP name, false otherwise.

See Also
getPrefix(int posn)
startsWithback to summary
public boolean startsWith(List<Rdn> rdns)

Determines whether the specified RDN sequence forms a prefix of this LDAP name. Returns true if this LdapName is at least as long as rdns, and for every position p in the range [0, rdns.size()) the component getRdn(p) matches rdns.get(p). Returns false otherwise. If rdns is null, false is returned.

Parameters
rdns:List<Rdn>

The sequence of Rdns to check.

Returns:boolean

true if rdns form a prefix of this LDAP name, false otherwise.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a string representation of this LDAP name in a format defined by RFC 2253 and described in the class description. If the name has zero components an empty string is returned.

Returns:String

The string representation of the LdapName.

writeObjectback to summary
private void writeObject(ObjectOutputStream s) throws IOException

The writeObject method is called to save the state of the LdapName to a stream. Serializes only the unparsed DN, for compactness and to avoid any implementation dependency.

Parameters
s:ObjectOutputStream

the ObjectOutputStream to write to

Annotations
@Serial
Exceptions
IOException:
if an I/O error occurs
Serial data
The DN String representation of this LDAP name.