@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class DN extends java.lang.Object implements java.lang.Comparable<DN>, java.util.Comparator<DN>, java.io.Serializable
o=example.com
". This is a DN with a single, single-valued
RDN. The RDN attribute is "o
" and the RDN value is
"example.com
".givenName=John+sn=Doe,ou=People,dc=example,dc=com
". This is a
DN with four different RDNs ("givenName=John+sn=Doe"
,
"ou=People
", "dc=example
", and "dc=com
". The
first RDN is multivalued with attribute-value pairs of
"givenName=John
" and "sn=Doe
".uid=john.doe,ou=people,dc=example,dc=com
" and
"UID = JOHN.DOE , OU = PEOPLE , DC = EXAMPLE , DC = COM
" actually
refer to the same distinguished name. To deal with these differences, the
normalized representation may be used. The normalized representation is a
standardized way of representing a DN, and it is obtained by eliminating any
unnecessary spaces and converting all non-case-sensitive characters to
lowercase. The normalized representation of a DN may be obtained using the
toNormalizedString()
method, and two DNs may be compared to
determine if they are equal using the standard equals(java.lang.Object)
method.
uid=john.doe,ou=People,o=example.com
", the entry
"o=example.com
" is at the root of the DIT, the entry
"ou=People,o=example.com
" is an immediate descendant of the
"o=example.com
" entry, and the
"uid=john.doe,ou=People,o=example.com
" entry is an immediate
descendant of the "ou=People,o=example.com
" entry. Similarly, the
entry "uid=jane.doe,ou=People,o=example.com
" would be considered a
peer of the "uid=john.doe,ou=People,o=example.com
" entry because they
have the same parent.
uid=john.doe,ou=People,dc=example,dc=com
", the directory server may
or may not actually have a "dc=com
" entry. In many such cases, the
base entry may actually be just "dc=example,dc=com
". The DNs of the
entries that are at the base of the directory information tree are called
"naming contexts" or "suffixes" and they are generally available in the
namingContexts
attribute of the root DSE. See the RootDSE
class for more information about interacting with the server root DSE.
isAncestorOf(com.unboundid.ldap.sdk.DN, boolean)
and isDescendantOf(com.unboundid.ldap.sdk.DN, boolean)
methods may be used to
determine whether two DNs have a hierarchical relationship. In addition,
this class implements the Comparable
and Comparator
interfaces so that it may be used to easily sort DNs (ancestors will always
be sorted before descendants, and peers will always be sorted
lexicographically based on their normalized representations).Modifier and Type | Field and Description |
---|---|
static DN |
NULL_DN
A pre-allocated DN object equivalent to the null DN.
|
Constructor and Description |
---|
DN(java.util.List<RDN> rdns)
Creates a new DN with the provided set of RDNs.
|
DN(RDN... rdns)
Creates a new DN with the provided set of RDNs.
|
DN(RDN rdn,
DN parentDN)
Creates a new DN below the provided parent DN with the given RDN.
|
DN(java.lang.String dnString)
Creates a new DN from the provided string representation.
|
DN(java.lang.String dnString,
Schema schema)
Creates a new DN from the provided string representation.
|
Modifier and Type | Method and Description |
---|---|
int |
compare(DN dn1,
DN dn2)
Compares the provided DN values to determine their relative order in a
sorted list.
|
static int |
compare(java.lang.String s1,
java.lang.String s2)
Compares the DNs with the provided string representations to determine
their relative order in a sorted list.
|
static int |
compare(java.lang.String s1,
java.lang.String s2,
Schema schema)
Compares the DNs with the provided string representations to determine
their relative order in a sorted list.
|
int |
compareTo(DN dn)
Compares the provided DN to this DN to determine their relative order in
a sorted list.
|
boolean |
equals(java.lang.Object o)
Indicates whether the provided object is equal to this DN.
|
boolean |
equals(java.lang.String s)
Indicates whether the DN with the provided string representation is equal
to this DN.
|
static boolean |
equals(java.lang.String s1,
java.lang.String s2)
Indicates whether the two provided strings represent the same DN.
|
DN |
getParent()
Retrieves the DN that is the parent for this DN.
|
static DN |
getParent(java.lang.String s)
Retrieves the DN that is the parent for the DN with the provided string
representation.
|
java.lang.String |
getParentString()
Retrieves the string representation of the DN that is the parent for this
DN.
|
static java.lang.String |
getParentString(java.lang.String s)
Retrieves the string representation of the DN that is the parent for the
DN with the provided string representation.
|
RDN |
getRDN()
Retrieves the leftmost (i.e., furthest from the naming context) RDN
component for this DN.
|
RDN[] |
getRDNs()
Retrieves the set of RDNs that comprise this DN.
|
static RDN[] |
getRDNs(java.lang.String s)
Retrieves the set of RDNs that comprise the DN with the provided string
representation.
|
java.lang.String |
getRDNString()
Retrieves the string representation of the leftmost (i.e., furthest from
the naming context) RDN component for this DN.
|
static java.lang.String |
getRDNString(java.lang.String s)
Retrieves the string representation of the leftmost (i.e., furthest from
the naming context) RDN component for the DN with the provided string
representation.
|
java.lang.String[] |
getRDNStrings()
Retrieves the set of string representations of the RDNs that comprise this
DN.
|
static java.lang.String[] |
getRDNStrings(java.lang.String s)
Retrieves the set of string representations of the RDNs that comprise this
DN.
|
int |
hashCode()
Generates a hash code for this DN.
|
boolean |
isAncestorOf(DN dn,
boolean allowEquals)
Indicates whether this DN is an ancestor of the provided DN.
|
boolean |
isAncestorOf(java.lang.String s,
boolean allowEquals)
Indicates whether this DN is an ancestor of the DN with the provided string
representation.
|
static boolean |
isAncestorOf(java.lang.String s1,
java.lang.String s2,
boolean allowEquals)
Indicates whether the DN represented by the first string is an ancestor of
the DN represented by the second string.
|
boolean |
isDescendantOf(DN dn,
boolean allowEquals)
Indicates whether this DN is a descendant of the provided DN.
|
boolean |
isDescendantOf(java.lang.String s,
boolean allowEquals)
Indicates whether this DN is a descendant of the DN with the provided
string representation.
|
static boolean |
isDescendantOf(java.lang.String s1,
java.lang.String s2,
boolean allowEquals)
Indicates whether the DN represented by the first string is a descendant of
the DN represented by the second string.
|
boolean |
isNullDN()
Indicates whether this DN represents the null DN, which does not have any
RDN components.
|
static boolean |
isValidDN(java.lang.String s)
Indicates whether the provided string represents a valid DN.
|
boolean |
matchesBaseAndScope(DN baseDN,
SearchScope scope)
Indicates whether this DN falls within the range of the provided search
base DN and scope.
|
boolean |
matchesBaseAndScope(java.lang.String baseDN,
SearchScope scope)
Indicates whether this DN falls within the range of the provided search
base DN and scope.
|
static java.lang.String |
normalize(java.lang.String s)
Retrieves a normalized representation of the DN with the provided string
representation.
|
static java.lang.String |
normalize(java.lang.String s,
Schema schema)
Retrieves a normalized representation of the DN with the provided string
representation.
|
java.lang.String |
toMinimallyEncodedString()
Retrieves a string representation of this DN with minimal encoding for
special characters.
|
java.lang.String |
toNormalizedString()
Retrieves a normalized string representation of this DN.
|
void |
toNormalizedString(java.lang.StringBuilder buffer)
Appends a normalized string representation of this DN to the provided
buffer.
|
java.lang.String |
toString()
Retrieves a string representation of this DN.
|
void |
toString(java.lang.StringBuilder buffer)
Appends a string representation of this DN to the provided buffer.
|
void |
toString(java.lang.StringBuilder buffer,
boolean minimizeEncoding)
Appends a string representation of this DN to the provided buffer.
|
public DN(RDN... rdns)
rdns
- The RDN components for this DN. It must not be null
.public DN(java.util.List<RDN> rdns)
rdns
- The RDN components for this DN. It must not be null
.public DN(RDN rdn, DN parentDN)
rdn
- The RDN for the new DN. It must not be null
.parentDN
- The parent DN for the new DN to create. It must not be
null
.public DN(java.lang.String dnString) throws LDAPException
dnString
- The string representation to use to create this DN. It
must not be null
.LDAPException
- If the provided string cannot be parsed as a valid
DN.public DN(java.lang.String dnString, Schema schema) throws LDAPException
dnString
- The string representation to use to create this DN. It
must not be null
.schema
- The schema to use to generate the normalized string
representation of this DN. It may be null
if no
schema is available.LDAPException
- If the provided string cannot be parsed as a valid
DN.public static boolean isValidDN(java.lang.String s)
s
- The string for which to make the determination. It must not be
null
.true
if the provided string represents a valid DN, or
false
if not.public RDN getRDN()
null
if this DN
does not have any RDNs (i.e., it is the null DN).public java.lang.String getRDNString()
null
if this DN does not have any RDNs (i.e., it is
the null DN).public static java.lang.String getRDNString(java.lang.String s) throws LDAPException
s
- The string representation of the DN to process. It must not be
null
.null
if this DN does not have any RDNs (i.e., it is
the null DN).LDAPException
- If the provided string cannot be parsed as a DN.public RDN[] getRDNs()
public static RDN[] getRDNs(java.lang.String s) throws LDAPException
s
- The string representation of the DN for which to retrieve the
RDNs. It must not be null
.LDAPException
- If the provided string cannot be parsed as a DN.public java.lang.String[] getRDNStrings()
public static java.lang.String[] getRDNStrings(java.lang.String s) throws LDAPException
s
- The string representation of the DN for which to retrieve the
RDN strings. It must not be null
.LDAPException
- If the provided string cannot be parsed as a DN.public boolean isNullDN()
true
if this DN represents the null DN, or false
if not.public DN getParent()
null
if there
is no parent.public static DN getParent(java.lang.String s) throws LDAPException
s
- The string representation of the DN for which to retrieve the
parent. It must not be null
.null
if there
is no parent.LDAPException
- If the provided string cannot be parsed as a DN.public java.lang.String getParentString()
null
if there
is no parent.public static java.lang.String getParentString(java.lang.String s) throws LDAPException
s
- The string representation of the DN for which to retrieve the
parent. It must not be null
.null
if there
is no parent.LDAPException
- If the provided string cannot be parsed as a DN.public boolean isAncestorOf(DN dn, boolean allowEquals)
allowEquals
is false
).dn
- The DN for which to make the determination.allowEquals
- Indicates whether a DN should be considered an
ancestor of itself.true
if this DN may be considered an ancestor of the
provided DN, or false
if not.public boolean isAncestorOf(java.lang.String s, boolean allowEquals) throws LDAPException
allowEquals
is false
).s
- The string representation of the DN for which to make
the determination.allowEquals
- Indicates whether a DN should be considered an
ancestor of itself.true
if this DN may be considered an ancestor of the
provided DN, or false
if not.LDAPException
- If the provided string cannot be parsed as a DN.public static boolean isAncestorOf(java.lang.String s1, java.lang.String s2, boolean allowEquals) throws LDAPException
allowEquals
is
false
).s1
- The string representation of the first DN for which to
make the determination.s2
- The string representation of the second DN for which
to make the determination.allowEquals
- Indicates whether a DN should be considered an
ancestor of itself.true
if the first DN may be considered an ancestor of the
second DN, or false
if not.LDAPException
- If either of the provided strings cannot be parsed
as a DN.public boolean isDescendantOf(DN dn, boolean allowEquals)
allowEquals
is
true
).dn
- The DN for which to make the determination.allowEquals
- Indicates whether a DN should be considered a
descendant of itself.true
if this DN may be considered a descendant of the
provided DN, or false
if not.public boolean isDescendantOf(java.lang.String s, boolean allowEquals) throws LDAPException
allowEquals
is true
).s
- The string representation of the DN for which to make
the determination.allowEquals
- Indicates whether a DN should be considered a
descendant of itself.true
if this DN may be considered a descendant of the
provided DN, or false
if not.LDAPException
- If the provided string cannot be parsed as a DN.public static boolean isDescendantOf(java.lang.String s1, java.lang.String s2, boolean allowEquals) throws LDAPException
allowEquals
is
true
).s1
- The string representation of the first DN for which to
make the determination.s2
- The string representation of the second DN for which
to make the determination.allowEquals
- Indicates whether a DN should be considered an
ancestor of itself.true
if this DN may be considered a descendant of the
provided DN, or false
if not.LDAPException
- If either of the provided strings cannot be parsed
as a DN.public boolean matchesBaseAndScope(java.lang.String baseDN, SearchScope scope) throws LDAPException
baseDN
- The base DN for which to make the determination. It must
not be null
.scope
- The scope for which to make the determination. It must not
be null
.true
if this DN is within the range of the provided base
and scope, or false
if not.LDAPException
- If a problem occurs while making the determination.public boolean matchesBaseAndScope(DN baseDN, SearchScope scope) throws LDAPException
baseDN
- The base DN for which to make the determination. It must
not be null
.scope
- The scope for which to make the determination. It must not
be null
.true
if this DN is within the range of the provided base
and scope, or false
if not.LDAPException
- If a problem occurs while making the determination.public int hashCode()
hashCode
in class java.lang.Object
public boolean equals(java.lang.Object o)
equals
in interface java.util.Comparator<DN>
equals
in class java.lang.Object
o
- The object for which to make the determination.true
if the provided object is considered equal to this
DN, or false
if not.public boolean equals(java.lang.String s) throws LDAPException
s
- The string representation of the DN to compare with this DN.true
if the DN with the provided string representation is
equal to this DN, or false
if not.LDAPException
- If the provided string cannot be parsed as a DN.public static boolean equals(java.lang.String s1, java.lang.String s2) throws LDAPException
s1
- The string representation of the first DN for which to make the
determination. It must not be null
.s2
- The string representation of the second DN for which to make
the determination. It must not be null
.true
if the provided strings represent the same DN, or
false
if not.LDAPException
- If either of the provided strings cannot be parsed
as a DN.public java.lang.String toString()
toString
in class java.lang.Object
public java.lang.String toMinimallyEncodedString()
public void toString(java.lang.StringBuilder buffer)
buffer
- The buffer to which to append the string representation of
this DN.public void toString(java.lang.StringBuilder buffer, boolean minimizeEncoding)
buffer
- The buffer to which the string representation is
to be appended.minimizeEncoding
- Indicates whether to restrict the encoding of
special characters to the bare minimum required
by LDAP (as per RFC 4514 section 2.4). If this
is true
, then only leading and trailing
spaces, double quotes, plus signs, commas,
semicolons, greater-than, less-than, and
backslash characters will be encoded.public java.lang.String toNormalizedString()
public void toNormalizedString(java.lang.StringBuilder buffer)
buffer
- The buffer to which to append the normalized string
representation of this DN.public static java.lang.String normalize(java.lang.String s) throws LDAPException
s
- The string representation of the DN to normalize. It must not
be null
.LDAPException
- If the provided string cannot be parsed as a DN.public static java.lang.String normalize(java.lang.String s, Schema schema) throws LDAPException
s
- The string representation of the DN to normalize. It must
not be null
.schema
- The schema to use to generate the normalized string
representation of the DN. It may be null
if no
schema is available.LDAPException
- If the provided string cannot be parsed as a DN.public int compareTo(DN dn)
compareTo
in interface java.lang.Comparable<DN>
dn
- The DN to compare against this DN. It must not be
null
.public int compare(DN dn1, DN dn2)
compare
in interface java.util.Comparator<DN>
dn1
- The first DN to be compared. It must not be null
.dn2
- The second DN to be compared. It must not be null
.public static int compare(java.lang.String s1, java.lang.String s2) throws LDAPException
s1
- The string representation for the first DN to be compared. It
must not be null
.s2
- The string representation for the second DN to be compared. It
must not be null
.LDAPException
- If either of the provided strings cannot be parsed
as a DN.public static int compare(java.lang.String s1, java.lang.String s2, Schema schema) throws LDAPException
s1
- The string representation for the first DN to be compared.
It must not be null
.s2
- The string representation for the second DN to be compared.
It must not be null
.schema
- The schema to use to generate the normalized string
representations of the DNs. It may be null
if no
schema is available.LDAPException
- If either of the provided strings cannot be parsed
as a DN.