public final class DN extends Object implements Iterable<RDN>, Comparable<DN>
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
| Modifier and Type | Class and Description |
|---|---|
static class |
DN.CompactDn
A compact representation of a DN, suitable for equality and comparisons, and providing a natural hierarchical
ordering.
|
| 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.
|
DN.CompactDn |
compact()
Returns a compact representation of this DN, with lazy evaluation of the normalized value.
|
int |
compareTo(DN 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 |
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()
Returns
true if this DN is the Root DN. |
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 |
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. |
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. |
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. |
static DN |
rootDN()
Returns the Root DN.
|
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.
|
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.
|
public static String escapeAttributeValue(Object attributeValue)
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.attributeValue - The attribute value.public static DN format(String template, Object... attributeValues)
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");
template - The DN template.attributeValues - The attribute values to be substituted into the template.DN.LocalizedIllegalArgumentException - If the formatted template is not a valid LDAP string
representation of a DN.escapeAttributeValue(Object)public static DN format(String template, Schema schema, Object... attributeValues)
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");
template - The DN template.schema - The schema to use when parsing the DN.attributeValues - The attribute values to be substituted into the template.DN.LocalizedIllegalArgumentException - If the formatted template is not a valid LDAP string
representation of a DN.escapeAttributeValue(Object)public static DN rootDN()
public static DN valueOf(String dn)
dn - The LDAP string representation of a DN.LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a
DN.NullPointerException - If dn was null.format(String, Object...)public static DN valueOf(String dn, Schema schema)
dn - The LDAP string representation of a DN.schema - The schema to use when parsing the DN.LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a
DN.NullPointerException - If dn or schema was null.format(String, Schema, Object...)public DN child(DN dn)
dn - The DN containing the RDN components to be added to this DN.NullPointerException - If dn was null.public DN child(RDN 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.
rdn - The RDN for the child DN.NullPointerException - If rdn was null.RDN.maxValue()public DN child(String dn)
dn - The DN containing the RDN components to be added to this DN.LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a
DN.NullPointerException - If dn was null.public DN child(String attributeType, Object attributeValue)
If attributeValue is not an instance of ByteString then
it will be converted using the ByteString.valueOf(Object) method.
attributeType - The attribute type.attributeValue - The attribute value.UnknownSchemaElementException - If attributeType was not found in the default schema.NullPointerException - If attributeType or attributeValue was
null.public int compareTo(DN dn)
compareTo in interface Comparable<DN>public boolean isChildOf(DN dn)
true if this DN is an immediate child of the provided DN.dn - The potential parent DN.true if this DN is the immediate child of the provided
DN, otherwise false.NullPointerException - If dn was null.public boolean isChildOf(String dn)
true if this DN is an immediate child of the provided DN
decoded using the default schema.dn - The potential parent DN.true if this DN is the immediate child of the provided
DN, otherwise false.LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a
DN.NullPointerException - If dn was null.public boolean isInScopeOf(DN dn, SearchScope scope)
true if this DN matches the provided base DN and search
scope.dn - The base DN.scope - The search scope.true if this DN matches the provided base DN and search
scope, otherwise false.NullPointerException - If dn or scope was null.public boolean isInScopeOf(String dn, SearchScope scope)
true if this DN matches the provided base DN and search
scope.dn - The base DN.scope - The search scope.true if this DN matches the provided base DN and search
scope, otherwise false.LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a
DN.NullPointerException - If dn or scope was null.public boolean isParentOf(DN dn)
true if this DN is the immediate parent of the provided
DN.dn - The potential child DN.true if this DN is the immediate parent of the provided
DN, otherwise false.NullPointerException - If dn was null.public boolean isParentOf(String dn)
true if this DN is the immediate parent of the provided
DN.dn - The potential child DN.true if this DN is the immediate parent of the provided
DN, otherwise false.LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a
DN.NullPointerException - If dn was null.public boolean isRootDN()
true if this DN is the Root DN.true if this DN is the Root DN, otherwise false.public boolean isSubordinateOrEqualTo(DN dn)
true if this DN is subordinate to or equal to the
provided DN.dn - The potential child DN.true if this DN is subordinate to or equal to the
provided DN, otherwise false.NullPointerException - If dn was null.public boolean isSubordinateOrEqualTo(String dn)
true if this DN is subordinate to or equal to the
provided DN.dn - The potential child DN.true if this DN is subordinate to or equal to the
provided DN, otherwise false.LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a
DN.NullPointerException - If dn was null.public boolean isSuperiorOrEqualTo(DN dn)
true if this DN is superior to or equal to the provided
DN.dn - The potential child DN.true if this DN is superior to or equal to the provided
DN, otherwise false.NullPointerException - If dn was null.public boolean isSuperiorOrEqualTo(String dn)
true if this DN is superior to or equal to the provided
DN.dn - The potential child DN.true if this DN is superior to or equal to the provided
DN, otherwise false.LocalizedIllegalArgumentException - If dn is not a valid LDAP string representation of a
DN.NullPointerException - If dn was null.public Iterator<RDN> iterator()
Attempts to remove RDNs using an iterator's remove() method are
not permitted and will result in an UnsupportedOperationException
being thrown.
public DN localName(int index)
dn.localName(0).isRootDN(); dn.localName(1).equals(rootDN.child(dn.rdn())); dn.localName(dn.size()).equals(dn);
index - The number of RDNs to be included in the local name.IllegalArgumentException - If index is less than zero.public DN parent()
null
if this DN is the Root DN.
This method is equivalent to:
parent(1);
null
if this DN is the Root DN.public DN parent(int index)
index is zero then this DN will be
returned (identity).index - The number of RDNs to be removed.null if the parent of the Root DN is
reached.IllegalArgumentException - If index is less than zero.public RDN rdn()
null if this DN is the Root DN.null if this DN is the Root DN.public DN rename(DN fromDN, DN toDN)
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).fromDN - The old parent DN.toDN - The new parent DN.NullPointerException - If fromDN or toDN was null.public int size()
public String toString()
toString in class Objectpublic ByteString toNormalizedByteString()
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.
public String toNormalizedUrlSafeString()
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.
public DN.CompactDn compact()
Copyright © 2011-2015 ForgeRock AS. All Rights Reserved.