org.forgerock.opendj.ldap

Class Dn

java.lang.Object

org.forgerock.opendj.ldap.Dn

All Implemented Interfaces:

Comparable<Dn>, Iterable<Rdn>

public final class Dn
extends Object
implements Iterable<Rdn>, Comparable<Dn>

A distinguished name (DN) as defined in RFC 4512 section 2.3 is the concatenation of its relative distinguished name (RDN) and its immediate superior's DN. A DN unambiguously refers to an entry in the Directory.

The following are examples of string representations of DNs:

 UID=nobody@example.com,DC=example,DC=com CN=John
 Smith,OU=Sales,O=ACME Limited,L=Moab,ST=Utah,C=US
 

See Also:

RFC 4512 - Lightweight Directory Access Protocol (LDAP): Directory Information Models

Method Summary

Modifier and Type	Method and Description
Dn	child(Dn dn) Returns a DN which is subordinate to this DN and having the additional RDN components contained in the provided DN.
Dn	child(Rdn rdn) Returns a DN which is an immediate child of this DN and having the specified RDN.
Dn	child(String dn) Returns a DN which is subordinate to this DN and having the additional RDN components contained in the provided DN decoded using the default schema.
Dn	child(String attributeType, Object attributeValue) Returns a DN which is an immediate child of this DN and with an RDN having the provided attribute type and value decoded using the default schema.
int	compareTo(Dn dn)
static Dn	emptyDn() Returns the empty DN.
boolean	equals(Object obj)
static String	escapeAttributeValue(Object attributeValue) Returns the LDAP string representation of the provided DN attribute value in a form suitable for substitution directly into a DN string.
static Dn	format(String template, Object... attributeValues) Creates a new DN using the provided DN template and unescaped attribute values using the default schema.
static Dn	format(String template, Schema schema, Object... attributeValues) Creates a new DN using the provided DN template and unescaped attribute values using the provided schema.
int	hashCode()
boolean	isChildOf(Dn dn) Returns true if this DN is an immediate child of the provided DN.
boolean	isChildOf(String dn) Returns true if this DN is an immediate child of the provided DN decoded using the default schema.
boolean	isEmpty() Returns true if this DN contains zero RDN components.
boolean	isInScopeOf(Dn dn, SearchScope scope) Returns true if this DN matches the provided base DN and search scope.
boolean	isInScopeOf(String dn, SearchScope scope) Returns true if this DN matches the provided base DN and search scope.
boolean	isParentOf(Dn dn) Returns true if this DN is the immediate parent of the provided DN.
boolean	isParentOf(String dn) Returns true if this DN is the immediate parent of the provided DN.
boolean	isRootDn() Deprecated. use isEmpty() instead
boolean	isSubordinateOrEqualTo(Dn dn) Returns true if this DN is subordinate to or equal to the provided DN.
boolean	isSubordinateOrEqualTo(String dn) Returns true if this DN is subordinate to or equal to the provided DN.
boolean	isSubordinateTo(Dn dn) Returns true if this DN is subordinate to, but not equal to the provided DN.
boolean	isSubordinateTo(String dn) Returns true if this DN is subordinate to, but not equal to the provided DN.
boolean	isSuperiorOrEqualTo(Dn dn) Returns true if this DN is superior to or equal to the provided DN.
boolean	isSuperiorOrEqualTo(String dn) Returns true if this DN is superior to or equal to the provided DN.
boolean	isSuperiorTo(Dn dn) Returns true if this DN is superior to, but not equal to the provided DN.
boolean	isSuperiorTo(String dn) Returns true if this DN is superior to, but not equal to the provided DN.
Iterator<Rdn>	iterator() Returns an iterator of the RDNs contained in this DN.
Dn	localName(int index) Returns the DN whose content is the specified number of RDNs from this DN.
Dn	parent() Returns the DN which is the immediate parent of this DN, or null if this DN is the Root DN.
Dn	parent(int index) Returns the DN which is equal to this DN with the specified number of RDNs removed.
Rdn	rdn() Returns the RDN of this DN, or null if this DN is the Root DN.
Rdn	rdn(int index) Returns the RDN at the specified index for this DN, or null if no such RDN exists.
Dn	rename(Dn fromDN, Dn toDN) Returns a copy of this DN whose parent DN, fromDN, has been renamed to the new parent DN, toDN.
Dn	rename(Rdn newRdn, Dn newSuperior) Returns a DN whose value is the result of applying LDAP modify DN semantics to this DN.
static Dn	rootDn() Deprecated. use emptyDn() instead
int	size() Returns the number of RDN components in this DN.
ByteString	toNormalizedByteString() Retrieves a normalized byte string representation of this DN.
String	toNormalizedUrlSafeString() Retrieves a normalized string representation of this DN.
String	toString() Returns the RFC 4514 string representation of this DN.
UUID	toUuid() Returns a UUID whose content is based on the normalized content of this DN.
static Dn	valueOf(ByteString dn) Parses the provided LDAP string representation of a DN using the default schema.
static Dn	valueOf(String dn) Parses the provided LDAP string representation of a DN using the default schema.
static Dn	valueOf(String dn, Schema schema) Parses the provided LDAP string representation of a DN using the provided schema.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

escapeAttributeValue

public static String escapeAttributeValue(Object attributeValue)

Returns the LDAP string representation of the provided DN attribute value in a form suitable for substitution directly into a DN string. This method may be useful in cases where a DN is to be constructed from a DN template using String#format(String, Object...). The following example illustrates two approaches to constructing a DN:

 // This may contain user input.
 String attributeValue = ...;

 // Using the equality filter constructor:
 DN dn = DN.valueOf("ou=people,dc=example,dc=com").child("uid", attributeValue);

 // Using a String template:
 String dnTemplate = "uid=%s,ou=people,dc=example,dc=com";
 String dnString = String.format(dnTemplate,
                                 DN.escapeAttributeValue(attributeValue));
 DN dn = DN.valueOf(dnString);
 

Note: attribute values do not and should not be escaped before passing them to constructors like child(String, Object). Escaping is only required when creating DN strings.

Parameters:

attributeValue - The attribute value.

Returns:

The LDAP string representation of the provided filter assertion value in a form suitable for substitution directly into a filter string.

format

public static Dn format(String template,
                        Object... attributeValues)
                 throws LocalizedIllegalArgumentException

Creates a new DN using the provided DN template and unescaped attribute values using the default schema. This method first escapes each of the attribute values and then substitutes them into the template using String.format(String, Object...). Finally, the formatted string is parsed as an LDAP DN using valueOf(String).

This method may be useful in cases where the structure of a DN is not known at compile time, for example, it may be obtained from a configuration file. Example usage:

 String template = "uid=%s,ou=people,dc=example,dc=com";
 DN dn = DN.format(template, "bjensen");
 

Parameters:

template - The DN template.

attributeValues - The attribute values to be substituted into the template.

Returns:

The formatted template parsed as a DN.

Throws:

LocalizedIllegalArgumentException - If the formatted template is not a valid LDAP string representation of a DN.

See Also:

escapeAttributeValue(Object)

format

public static Dn format(String template,
                        Schema schema,
                        Object... attributeValues)
                 throws LocalizedIllegalArgumentException

Creates a new DN using the provided DN template and unescaped attribute values using the provided schema. This method first escapes each of the attribute values and then substitutes them into the template using String.format(String, Object...). Finally, the formatted string is parsed as an LDAP DN using valueOf(String).

This method may be useful in cases where the structure of a DN is not known at compile time, for example, it may be obtained from a configuration file. Example usage:

 String template = "uid=%s,ou=people,dc=example,dc=com";
 DN dn = DN.format(template, "bjensen");
 

Parameters:

template - The DN template.

schema - The schema to use when parsing the DN.

attributeValues - The attribute values to be substituted into the template.

Returns:

The formatted template parsed as a DN.

Throws:

LocalizedIllegalArgumentException - If the formatted template is not a valid LDAP string representation of a DN.

See Also:

escapeAttributeValue(Object)

emptyDn

public static Dn emptyDn()

Returns the empty DN. The empty DN does not contain any RDN components and is superior to all other DNs.

Returns:

The empty DN.

rootDn

@Deprecated
public static Dn rootDn()

Deprecated. use emptyDn() instead

Returns the Root DN which represents the root of a tree. It is a synonym to the empty DN.

Returns:

The Root DN.

valueOf

public static Dn valueOf(String dn)
                  throws LocalizedIllegalArgumentException

Parses the provided LDAP string representation of a DN using the default schema.

Parameters:

dn - The LDAP string representation of a DN.

Returns:

The parsed DN.

Throws:

LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.

NullPointerException - If dn was null.

See Also:

format(String, Object...)

valueOf

public static Dn valueOf(String dn,
                         Schema schema)
                  throws LocalizedIllegalArgumentException

Parses the provided LDAP string representation of a DN using the provided schema.

Parameters:

dn - The LDAP string representation of a DN.

schema - The schema to use when parsing the DN.

Returns:

The parsed DN.

Throws:

LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.

NullPointerException - If dn or schema was null.

See Also:

format(String, Schema, Object...)

valueOf

public static Dn valueOf(ByteString dn)
                  throws LocalizedIllegalArgumentException

Parses the provided LDAP string representation of a DN using the default schema.

Parameters:

dn - The LDAP byte string representation of a DN.

Returns:

The parsed DN.

Throws:

LocalizedIllegalArgumentException - If dn is not a valid LDAP byte string representation of a DN.

NullPointerException - If dn was null.

child

public Dn child(Dn dn)

Returns a DN which is subordinate to this DN and having the additional RDN components contained in the provided DN.

Parameters:

dn - The DN containing the RDN components to be added to this DN.

Returns:

The subordinate DN.

Throws:

NullPointerException - If dn was null.

child

public Dn child(Rdn rdn)

Returns a DN which is an immediate child of this DN and having the specified RDN.

Note: the child DN whose RDN is Rdn.maxValue() compares greater than all other possible child DNs, and may be used to construct range queries against DN keyed sorted collections such as SortedSet and SortedMap.

Parameters:

rdn - The RDN for the child DN.

Returns:

The child DN.

Throws:

NullPointerException - If rdn was null.

See Also:

Rdn.maxValue()

child

public Dn child(String dn)
         throws LocalizedIllegalArgumentException

Returns a DN which is subordinate to this DN and having the additional RDN components contained in the provided DN decoded using the default schema.

Parameters:

dn - The DN containing the RDN components to be added to this DN.

Returns:

The subordinate DN.

Throws:

LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.

NullPointerException - If dn was null.

child

public Dn child(String attributeType,
                Object attributeValue)

Returns a DN which is an immediate child of this DN and with an RDN having the provided attribute type and value decoded using the default schema.

If attributeValue is not an instance of ByteString then it will be converted using the ByteString.valueOfObject(Object) method.

Parameters:

attributeType - The attribute type.

attributeValue - The attribute value.

Returns:

The child DN.

Throws:

UnknownSchemaElementException - If attributeType was not found in the default schema.

NullPointerException - If attributeType or attributeValue was null.

compareTo

public int compareTo(Dn dn)

Specified by:

compareTo in interface Comparable<Dn>

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

isChildOf

public boolean isChildOf(Dn dn)

Returns true if this DN is an immediate child of the provided DN.

Parameters:

dn - The potential parent DN.

Returns:

true if this DN is the immediate child of the provided DN, otherwise false.

Throws:

NullPointerException - If dn was null.

isChildOf

public boolean isChildOf(String dn)
                  throws LocalizedIllegalArgumentException

Returns true if this DN is an immediate child of the provided DN decoded using the default schema.

Parameters:

dn - The potential parent DN.

Returns:

true if this DN is the immediate child of the provided DN, otherwise false.

Throws:

LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.

NullPointerException - If dn was null.

isInScopeOf

public boolean isInScopeOf(Dn dn,
                           SearchScope scope)

Returns true if this DN matches the provided base DN and search scope.

Parameters:

dn - The base DN.

scope - The search scope.

Returns:

true if this DN matches the provided base DN and search scope, otherwise false.

Throws:

NullPointerException - If dn or scope was null.

isInScopeOf

public boolean isInScopeOf(String dn,
                           SearchScope scope)
                    throws LocalizedIllegalArgumentException

Returns true if this DN matches the provided base DN and search scope.

Parameters:

dn - The base DN.

scope - The search scope.

Returns:

true if this DN matches the provided base DN and search scope, otherwise false.

Throws:

LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.

NullPointerException - If dn or scope was null.

isParentOf

public boolean isParentOf(Dn dn)

Returns true if this DN is the immediate parent of the provided DN.

Parameters:

dn - The potential child DN.

Returns:

true if this DN is the immediate parent of the provided DN, otherwise false.

Throws:

NullPointerException - If dn was null.

isParentOf

public boolean isParentOf(String dn)
                   throws LocalizedIllegalArgumentException

Returns true if this DN is the immediate parent of the provided DN.

Parameters:

dn - The potential child DN.

Returns:

true if this DN is the immediate parent of the provided DN, otherwise false.

Throws:

LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.

NullPointerException - If dn was null.

isRootDn

@Deprecated
public boolean isRootDn()

Deprecated. use isEmpty() instead

Returns true if this DN contains zero RDN components. In other words, this method returns true if this DN is the empty DN.

Returns:

true if this DN contains zero RDN components.

See Also:

emptyDn()

isEmpty

public boolean isEmpty()

Returns true if this DN contains zero RDN components. In other words, this method returns true if this DN is the empty DN.

Returns:

true if this DN contains zero RDN components.

See Also:

emptyDn()

isSubordinateOrEqualTo

public boolean isSubordinateOrEqualTo(Dn dn)

Returns true if this DN is subordinate to or equal to the provided DN.

Parameters:

dn - The potential parent DN.

Returns:

true if this DN is subordinate to or equal to the provided DN, otherwise false.

Throws:

NullPointerException - If dn was null.

isSubordinateOrEqualTo

public boolean isSubordinateOrEqualTo(String dn)
                               throws LocalizedIllegalArgumentException

Returns true if this DN is subordinate to or equal to the provided DN.

Parameters:

dn - The potential parent DN.

Returns:

true if this DN is subordinate to or equal to the provided DN, otherwise false.

Throws:

LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.

NullPointerException - If dn was null.

isSubordinateTo

public boolean isSubordinateTo(String dn)

Returns true if this DN is subordinate to, but not equal to the provided DN.

Parameters:

dn - The potential parent DN.

Returns:

true if this DN is subordinate to, but not equal to the provided DN, otherwise false.

Throws:

NullPointerException - If dn was null.

isSubordinateTo

public boolean isSubordinateTo(Dn dn)

Returns true if this DN is subordinate to, but not equal to the provided DN.

Parameters:

dn - The potential parent DN.

Returns:

true if this DN is subordinate to, but not equal to the provided DN, otherwise false.

Throws:

NullPointerException - If dn was null.

isSuperiorOrEqualTo

public boolean isSuperiorOrEqualTo(Dn dn)

Returns true if this DN is superior to or equal to the provided DN.

Parameters:

dn - The potential child DN.

Returns:

true if this DN is superior to or equal to the provided DN, otherwise false.

Throws:

NullPointerException - If dn was null.

isSuperiorOrEqualTo

public boolean isSuperiorOrEqualTo(String dn)
                            throws LocalizedIllegalArgumentException

Returns true if this DN is superior to or equal to the provided DN.

Parameters:

dn - The potential child DN.

Returns:

true if this DN is superior to or equal to the provided DN, otherwise false.

Throws:

LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a DN.

NullPointerException - If dn was null.

isSuperiorTo

public boolean isSuperiorTo(String dn)

Returns true if this DN is superior to, but not equal to the provided DN.

Parameters:

dn - The potential child DN.

Returns:

true if this DN is superior to, but not equal to the provided DN, otherwise false.

Throws:

NullPointerException - If dn was null.

isSuperiorTo

public boolean isSuperiorTo(Dn dn)

Returns true if this DN is superior to, but not equal to the provided DN.

Parameters:

dn - The potential child DN.

Returns:

true if this DN is superior to, but not equal to the provided DN, otherwise false.

Throws:

NullPointerException - If dn was null.

iterator

public Iterator<Rdn> iterator()

Returns an iterator of the RDNs contained in this DN. The RDNs will be returned in the order starting with this DN's RDN, followed by the RDN of the parent DN, and so on.

Attempts to remove RDNs using an iterator's remove() method are not permitted and will result in an UnsupportedOperationException being thrown.

Specified by:

iterator in interface Iterable<Rdn>

Returns:

An iterator of the RDNs contained in this DN.

localName

public Dn localName(int index)

Returns the DN whose content is the specified number of RDNs from this DN. The following equivalences hold:

 dn.localName(0).isRootDN();
 dn.localName(1).equals(rootDN.child(dn.rdn()));
 dn.localName(dn.size()).equals(dn);
 

Said otherwise, a new DN is built using index RDNs, retained in the same order, starting from the left.

Parameters:

index - The number of RDNs to be included in the local name.

Returns:

The DN whose content is the specified number of RDNs from this DN.

Throws:

IllegalArgumentException - If index is less than zero.

See Also:

for the reverse operation (starting from the right)

parent

public Dn parent()

Returns the DN which is the immediate parent of this DN, or null if this DN is the Root DN.

This method is equivalent to:

 parent(1);
 

Returns:

The DN which is the immediate parent of this DN, or null if this DN is the Root DN.

parent

public Dn parent(int index)

Returns the DN which is equal to this DN with the specified number of RDNs removed. Note that if index is zero then this DN will be returned (identity). Said otherwise, a new DN is built using index RDNs, retained in the same order, starting from the right.

Parameters:

index - The number of RDNs to be removed.

Returns:

The DN which is equal to this DN with the specified number of RDNs removed, or null if the parent of the Root DN is reached.

Throws:

IllegalArgumentException - If index is less than zero.

See Also:

for the reverse operation (starting from the left)

rdn

public Rdn rdn()

Returns the RDN of this DN, or null if this DN is the Root DN.

This is the equivalent of calling dn.rdn(0).

Returns:

The RDN of this DN, or null if this DN is the Root DN.

rdn

public Rdn rdn(int index)

Returns the RDN at the specified index for this DN, or null if no such RDN exists.

Here is an example usage:

 
 DN.valueOf("ou=people,dc=example,dc=com").rdn(0) => "ou=people"
 DN.valueOf("ou=people,dc=example,dc=com").rdn(1) => "dc=example"
 DN.valueOf("ou=people,dc=example,dc=com").rdn(2) => "dc=com"
 DN.valueOf("ou=people,dc=example,dc=com").rdn(3) => null
 
 

Parameters:

index - The index of the requested RDN.

Returns:

The RDN at the specified index, or null if no such RDN exists.

Throws:

IllegalArgumentException - If index is less than zero.

rename

public Dn rename(Dn fromDN,
                 Dn toDN)

Returns a copy of this DN whose parent DN, fromDN, has been renamed to the new parent DN, toDN. If this DN is not subordinate or equal to fromDN then this DN is returned (i.e. the DN is not renamed).

Parameters:

fromDN - The old parent DN.

toDN - The new parent DN.

Returns:

The renamed DN, or this DN if no renaming was performed.

Throws:

NullPointerException - If fromDN or toDN was null.

rename

public Dn rename(Rdn newRdn,
                 Dn newSuperior)

Returns a DN whose value is the result of applying LDAP modify DN semantics to this DN. Specifically, the parent of the returned DN will be newSuperior, if provided, otherwise it will be left unchanged. The RDN of the returned DN will be set to newRdn.

Parameters:

newRdn - The new RDN, which must not be null.

newSuperior - The optional new parent, which may be null indicating that the parent should remain the same.

Returns:

The renamed DN according to LDAP modify DN semantics.

Throws:

NullPointerException - If newRdn was null.

size

public int size()

Returns the number of RDN components in this DN.

Returns:

The number of RDN components in this DN.

toString

public String toString()

Returns the RFC 4514 string representation of this DN.

Overrides:

toString in class Object

Returns:

The RFC 4514 string representation of this DN.

See Also:

RFC 4514 - Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names

toNormalizedByteString

public ByteString toNormalizedByteString()

Retrieves a normalized byte string representation of this DN.

This representation is suitable for equality and comparisons, and for providing a natural hierarchical ordering. However, it is not a valid DN and can't be reverted to a valid DN. You should consider using a CompactDn as an alternative.

Returns:

The normalized string representation of this DN.

toNormalizedUrlSafeString

public String toNormalizedUrlSafeString()

Retrieves a normalized string representation of this DN.

This representation is safe to use in an URL or in a file name. However, it is not a valid DN and can't be reverted to a valid DN.

Returns:

The normalized string representation of this DN.

toUuid

public UUID toUuid()

Returns a UUID whose content is based on the normalized content of this DN. Two equivalent DNs subject to the same schema will always yield the same UUID.

Returns:

the UUID representing this DN