com.sun.jndi.ldap
Class LdapName

java.lang.Object
  com.sun.jndi.ldap.LdapName

All Implemented Interfaces:

Serializable, Cloneable, Comparable, Name

public final class LdapName
extends Object
implements Name

LdapName implements compound names for LDAP v3 as specified by RFC 2253.

RFC 2253 has a few ambiguities and outright inconsistencies. These are resolved as follows:

• RFC 2253 leaves the term "whitespace" undefined. The definition of "optional-space" given in RFC 1779 is used in its place: either a space character or a carriage return ("\r").
• Whitespace is allowed on either side of ',', ';', '=', and '+'. Such whitespace is accepted but not generated by this code, and is ignored when comparing names.
• AttributeValue strings containing '=' or non-leading '#' characters (unescaped) are accepted.

String names passed to LdapName or returned by it use the full 16-bit 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's "generous".

When names are tested for equality, attribute types and binary values are case-insensitive, and string values are by default 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.

See Also:

Serialized Form

Constructor Summary

LdapName(String name)
Constructs an LDAP name from the given DN.

Method Summary

Name	add(int pos, String comp) Inserts the given String component to this Name at the given index.
Name	add(String comp) Adds the given String component to the end of this Name.
Name	addAll(int pos, Name suffix) Inserts all the components of the given Name to this Name at the given index.
Name	addAll(Name suffix) Adds all the components of the given Name to the end of this Name.
Object	clone() clone creates a shallow clone of this.
int	compareTo(Object obj) Compares the given object to this Name.
boolean	endsWith(Name n) Returns true if this Name ends with the components of the given Name, false otherwise.
boolean	equals(Object obj) equals compares this object to another object.
static String	escapeAttributeValue(Object val) Given the value of an attribute, returns a string suitable for inclusion in a DN.
String	get(int pos) Gets the component at the given index.
Enumeration	getAll() Returns a non-null (but possibly empty) Enumeration of the components of the Name as Strings.
Name	getPrefix(int pos) Returns the components till the given index as a Name.
Name	getSuffix(int pos) Returns the components from the given index till the end as a Name.
int	hashCode() hashCode returns a hash code for this object.
boolean	isEmpty() Returns true if the number of components of this Name is zero, false otherwise.
Object	remove(int pos) Removes the component at the given index from this Name.
void	setValuesCaseSensitive(boolean caseSensitive) Controls whether string-values are treated as case-sensitive when the string values within names are compared.
int	size() Returns the number of components of this Name.
boolean	startsWith(Name n) Returns true if this Name starts with the components of the given Name, false otherwise.
String	toString() toString creates a printable string that represents this object for debugging purposes.
static Object	unescapeAttributeValue(String val) Given an attribute value formated according to RFC 2253, returns the unformated value.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

LdapName

public LdapName(String name)
         throws InvalidNameException

Constructs an LDAP name from the given DN.

Parameters:

name - An LDAP DN. To JNDI, a compound name.

Throws:

InvalidNameException - if a syntax violation is detected.

Method Detail

clone

public Object clone()

Description copied from class: Object

clone creates a shallow clone of this.

Specified by:

clone in interface Name

Overrides:

clone in class Object

Returns:

a clone of this object.

toString

public String toString()

Description copied from class: Object

toString creates a printable string that represents this object for debugging purposes.

The default implementation returns getClass().getName() + '@' + Integer.toHexString(hashCode()).

Overrides:

toString in class Object

Returns:

a string identifying this object.

equals

public boolean equals(Object obj)

Description copied from class: Object

equals compares this object to another object.

Equals must be symmetric (a.equals(b) == b.equals(a)), reflexive (a.equals(a)==true) and transitive (a.equals(b) && b.equals(c) IMPLIES (a.equals(c))) and not change over time (a.equals(b) == a.equals(b)). a.equals(null) should always return false.

If a.equals(b) is true for two objects a and b, then a.hashCode()==b.hashCode() must hold.

The default implementation of equals returns this==other.

Overrides:

equals in class Object

Parameters:

obj - the other object.

Returns:

if this and other are considered equal.

compareTo

public int compareTo(Object obj)

Description copied from interface: Name

Compares the given object to this Name. Returns a negative value if the given Object is smaller then this Name, a positive value if the Object is bigger, and zero if the are equal. If the Object is not of a class that can be compared to the class of this Name then a ClassCastException is thrown. Note that it is not guaranteed that Names implemented in different classes can be compared. The definition of smaller, bigger and equal is up to the actual implementing class.

Specified by:

compareTo in interface Comparable

Specified by:

compareTo in interface Name

Parameters:

obj - the other object

Returns:

a value <0 if this < o, 0 if this == o and a value > 0 if this > o.

hashCode

public int hashCode()

Description copied from class: Object

hashCode returns a hash code for this object. The hash code must be equal for two objects a and b if a.equals(b) is true.

The default implementation returns System.identityHashCode(this).

Overrides:

hashCode in class Object

Returns:

a hash code value.

size

public int size()

Description copied from interface: Name

Returns the number of components of this Name. The returned number can be zero.

Specified by:

size in interface Name

isEmpty

public boolean isEmpty()

Description copied from interface: Name

Returns true if the number of components of this Name is zero, false otherwise.

Specified by:

isEmpty in interface Name

getAll

public Enumeration getAll()

Description copied from interface: Name

Returns a non-null (but possibly empty) Enumeration of the components of the Name as Strings.

Specified by:

getAll in interface Name

get

public String get(int pos)

Description copied from interface: Name

Gets the component at the given index.

Specified by:

get in interface Name

getPrefix

public Name getPrefix(int pos)

Description copied from interface: Name

Returns the components till the given index as a Name. The returned Name can be modified without changing the original.

Specified by:

getPrefix in interface Name

getSuffix

public Name getSuffix(int pos)

Description copied from interface: Name

Returns the components from the given index till the end as a Name. The returned Name can be modified without changing the original.

Specified by:

getSuffix in interface Name

startsWith

public boolean startsWith(Name n)

Description copied from interface: Name

Returns true if this Name starts with the components of the given Name, false otherwise.

Specified by:

startsWith in interface Name

endsWith

public boolean endsWith(Name n)

Description copied from interface: Name

Returns true if this Name ends with the components of the given Name, false otherwise.

Specified by:

endsWith in interface Name

setValuesCaseSensitive

public void setValuesCaseSensitive(boolean caseSensitive)

Controls whether string-values are treated as case-sensitive when the string values within names are compared. The default behavior is case-insensitive comparison.

addAll

public Name addAll(Name suffix)
            throws InvalidNameException

Description copied from interface: Name

Adds all the components of the given Name to the end of this Name. The method modifies the current Name and then returns it.

Specified by:

addAll in interface Name

Throws:

InvalidNameException - if any of the given components is not a valid component for this Name.

addAll

public Name addAll(int pos,
                   Name suffix)
            throws InvalidNameException

Description copied from interface: Name

Inserts all the components of the given Name to this Name at the given index. The method modifies the current Name and then returns it.

Specified by:

addAll in interface Name

Throws:

InvalidNameException - if any of the given components is not a valid component for this Name.

add

public Name add(String comp)
         throws InvalidNameException

Description copied from interface: Name

Adds the given String component to the end of this Name. The method modifies the current Name and then returns it.

Specified by:

add in interface Name

Throws:

InvalidNameException - if the given String is not a valid component for this Name.

add

public Name add(int pos,
                String comp)
         throws InvalidNameException

Description copied from interface: Name

Inserts the given String component to this Name at the given index. The method modifies the current Name and then returns it.

Specified by:

add in interface Name

Throws:

InvalidNameException - if the given String is not a valid component for this Name.

remove

public Object remove(int pos)
              throws InvalidNameException

Description copied from interface: Name

Removes the component at the given index from this Name. The method modifies the current Name and then returns it.

Specified by:

remove in interface Name

Throws:

InvalidNameException - if the given String is not a valid component for this Name.

escapeAttributeValue

public static String escapeAttributeValue(Object val)

Given the value of an attribute, returns a string suitable for inclusion in a DN. If the value is a string, this is accomplished by using backslash (\) to escape the following characters:

• leading and trailing whitespace

• , = + < > # ; " \

If the value is a byte array, it is converted to hex notation (such as "#CEB1DF80").

unescapeAttributeValue

public static Object unescapeAttributeValue(String val)

Given an attribute value formated according to RFC 2253, returns the unformated value. Returns a string value as a string, and a binary value as a byte array.