com.unboundid.ldap.sdk

Class DN

java.lang.Object

com.unboundid.ldap.sdk.DN

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<DN>, java.util.Comparator<DN>

@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

This class provides a data structure for holding information about an LDAP distinguished name (DN). A DN consists of a comma-delimited list of zero or more RDN components. See RFC 4514 for more information about representing DNs and RDNs as strings.

Examples of valid DNs (excluding the quotation marks, which are provided for clarity) include:

• "" -- This is the zero-length DN (also called the null DN), which may be used to refer to the directory server root DSE.
• "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".

Note that there is some inherent ambiguity in the string representations of distinguished names. In particular, there may be differences in spacing (particularly around commas and equal signs, as well as plus signs in multivalued RDNs), and also differences in capitalization in attribute names and/or values. For example, the strings "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.

Distinguished names are hierarchical. The rightmost RDN refers to the root of the directory information tree (DIT), and each successive RDN to the left indicates the addition of another level of hierarchy. For example, in the DN "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.

Note that in some cases, the root of the DIT may actually contain a DN with multiple RDNs. For example, in the DN "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.

This class provides methods for making determinations based on the hierarchical relationships of DNs. For example, the 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).

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static DN	NULL_DN A pre-allocated DN object equivalent to the null DN.

Constructor Summary

Constructors

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.
DN(java.lang.String dnString, Schema schema, boolean strictNameChecking) Creates a new DN from the provided string representation.

Method Summary

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.
static boolean	equals(java.lang.String s1, java.lang.String s2, Schema schema) Indicates whether the two provided strings represent the same DN.
static DNEscapingStrategy	getDNEscapingStrategy() Retrieves the escaping strategy that should be used by default when constructing the string representations of DNs and RDNs.
static DN	getDNRelativeToBaseDN(DN fullDN, DN baseDN) Retrieves a portion of the provided full DN that is relative to the given base DN (that is, the full DN with the base DN stripped off).
static java.lang.String	getDNRelativeToBaseDN(java.lang.String fullDN, java.lang.String baseDN) Retrieves a string that represents the portion of the provided full DN that is relative to the given base DN (that is, the full DN with the base DN stripped off).
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.
static boolean	isValidDN(java.lang.String s, boolean strictNameChecking) 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.
static void	setDNEscapingStrategy(DNEscapingStrategy dnEscapingStrategy) Specifies the escaping strategy that should be used by default when constructing the string representations of DNs and RDNs.
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(ByteStringBuffer buffer, DNEscapingStrategy escapingStrategy) Appends a string representation of this DN to the provided buffer.
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.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Comparator

comparing, comparing, comparingDouble, comparingInt, comparingLong, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

Field Detail

NULL_DN

@NotNull
public static final DN NULL_DN

A pre-allocated DN object equivalent to the null DN.

Constructor Detail

DN

public DN(@NotNull
          RDN... rdns)

Creates a new DN with the provided set of RDNs.

Parameters:

rdns - The RDN components for this DN. It must not be null.

DN

public DN(@NotNull
          java.util.List<RDN> rdns)

Creates a new DN with the provided set of RDNs.

Parameters:

rdns - The RDN components for this DN. It must not be null.

DN

public DN(@NotNull
          RDN rdn,
          @NotNull
          DN parentDN)

Creates a new DN below the provided parent DN with the given RDN.

Parameters:

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.

DN

public DN(@NotNull
          java.lang.String dnString)
   throws LDAPException

Creates a new DN from the provided string representation.

Parameters:

dnString - The string representation to use to create this DN. It must not be null.

Throws:

LDAPException - If the provided string cannot be parsed as a valid DN.

DN

public DN(@NotNull
          java.lang.String dnString,
          @Nullable
          Schema schema)
   throws LDAPException

Creates a new DN from the provided string representation.

Parameters:

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.

Throws:

LDAPException - If the provided string cannot be parsed as a valid DN.

DN

public DN(@NotNull
          java.lang.String dnString,
          @Nullable
          Schema schema,
          boolean strictNameChecking)
   throws LDAPException

Creates a new DN from the provided string representation.

Parameters:

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.

strictNameChecking - Indicates whether to verify that all attribute type names are valid as per RFC 4514. If this is false, then some technically invalid characters may be accepted in attribute type names. If this is true, then names must be strictly compliant.

Throws:

LDAPException - If the provided string cannot be parsed as a valid DN.

Method Detail

isValidDN

public static boolean isValidDN(@NotNull
                                java.lang.String s)

Indicates whether the provided string represents a valid DN.

Parameters:

s - The string for which to make the determination. It must not be null.

Returns:

true if the provided string represents a valid DN, or false if not.

isValidDN

public static boolean isValidDN(@NotNull
                                java.lang.String s,
                                boolean strictNameChecking)

Indicates whether the provided string represents a valid DN.

Parameters:

s - The string for which to make the determination. It must not be null.

strictNameChecking - Indicates whether to verify that all attribute type names are valid as per RFC 4514. If this is false, then some technically invalid characters may be accepted in attribute type names. If this is true, then names must be strictly compliant.

Returns:

true if the provided string represents a valid DN, or false if not.

getRDN

@Nullable
public RDN getRDN()

Retrieves the leftmost (i.e., furthest from the naming context) RDN component for this DN.

Returns:

The leftmost RDN component for this DN, or null if this DN does not have any RDNs (i.e., it is the null DN).

getRDNString

@Nullable
public java.lang.String getRDNString()

Retrieves the string representation of the leftmost (i.e., furthest from the naming context) RDN component for this DN.

Returns:

The string representation of the leftmost RDN component for this DN, or null if this DN does not have any RDNs (i.e., it is the null DN).

getRDNString

@Nullable
public static java.lang.String getRDNString(@NotNull
                                                      java.lang.String s)
                                               throws LDAPException

Retrieves the string representation of the leftmost (i.e., furthest from the naming context) RDN component for the DN with the provided string representation.

Parameters:

s - The string representation of the DN to process. It must not be null.

Returns:

The string representation of the leftmost RDN component for this DN, or null if this DN does not have any RDNs (i.e., it is the null DN).

Throws:

LDAPException - If the provided string cannot be parsed as a DN.

getRDNs

@NotNull
public RDN[] getRDNs()

Retrieves the set of RDNs that comprise this DN.

Returns:

The set of RDNs that comprise this DN.

getRDNs

@NotNull
public static RDN[] getRDNs(@NotNull
                                     java.lang.String s)
                              throws LDAPException

Retrieves the set of RDNs that comprise the DN with the provided string representation.

Parameters:

s - The string representation of the DN for which to retrieve the RDNs. It must not be null.

Returns:

The set of RDNs that comprise the DN with the provided string representation.

Throws:

LDAPException - If the provided string cannot be parsed as a DN.

getRDNStrings

@NotNull
public java.lang.String[] getRDNStrings()

Retrieves the set of string representations of the RDNs that comprise this DN.

Returns:

The set of string representations of the RDNs that comprise this DN.

getRDNStrings

@NotNull
public static java.lang.String[] getRDNStrings(@NotNull
                                                        java.lang.String s)
                                                 throws LDAPException

Retrieves the set of string representations of the RDNs that comprise this DN.

Parameters:

s - The string representation of the DN for which to retrieve the RDN strings. It must not be null.

Returns:

The set of string representations of the RDNs that comprise this DN.

Throws:

LDAPException - If the provided string cannot be parsed as a DN.

isNullDN

public boolean isNullDN()

Indicates whether this DN represents the null DN, which does not have any RDN components.

Returns:

true if this DN represents the null DN, or false if not.

getParent

@Nullable
public DN getParent()

Retrieves the DN that is the parent for this DN. Note that neither the null DN nor DNs consisting of a single RDN component will be considered to have parent DNs.

Returns:

The DN that is the parent for this DN, or null if there is no parent.

getParent

@Nullable
public static DN getParent(@NotNull
                                     java.lang.String s)
                              throws LDAPException

Retrieves the DN that is the parent for the DN with the provided string representation. Note that neither the null DN nor DNs consisting of a single RDN component will be considered to have parent DNs.

Parameters:

s - The string representation of the DN for which to retrieve the parent. It must not be null.

Returns:

The DN that is the parent for this DN, or null if there is no parent.

Throws:

LDAPException - If the provided string cannot be parsed as a DN.

getParentString

@Nullable
public java.lang.String getParentString()

Retrieves the string representation of the DN that is the parent for this DN. Note that neither the null DN nor DNs consisting of a single RDN component will be considered to have parent DNs.

Returns:

The DN that is the parent for this DN, or null if there is no parent.

getParentString

@Nullable
public static java.lang.String getParentString(@NotNull
                                                         java.lang.String s)
                                                  throws LDAPException

Retrieves the string representation of the DN that is the parent for the DN with the provided string representation. Note that neither the null DN nor DNs consisting of a single RDN component will be considered to have parent DNs.

Parameters:

s - The string representation of the DN for which to retrieve the parent. It must not be null.

Returns:

The DN that is the parent for this DN, or null if there is no parent.

Throws:

LDAPException - If the provided string cannot be parsed as a DN.

isAncestorOf

public boolean isAncestorOf(@NotNull
                            DN dn,
                            boolean allowEquals)

Indicates whether this DN is an ancestor of the provided DN. It will be considered an ancestor of the provided DN if the array of RDN components for the provided DN ends with the elements that comprise the array of RDN components for this DN (i.e., if the provided DN is subordinate to, or optionally equal to, this DN). The null DN will be considered an ancestor for all other DNs (with the exception of the null DN if allowEquals is false).

Parameters:

dn - The DN for which to make the determination.

allowEquals - Indicates whether a DN should be considered an ancestor of itself.

Returns:

true if this DN may be considered an ancestor of the provided DN, or false if not.

isAncestorOf

public boolean isAncestorOf(@NotNull
                            java.lang.String s,
                            boolean allowEquals)
                     throws LDAPException

Indicates whether this DN is an ancestor of the DN with the provided string representation. It will be considered an ancestor of the provided DN if the array of RDN components for the provided DN ends with the elements that comprise the array of RDN components for this DN (i.e., if the provided DN is subordinate to, or optionally equal to, this DN). The null DN will be considered an ancestor for all other DNs (with the exception of the null DN if allowEquals is false).

Parameters:

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.

Returns:

true if this DN may be considered an ancestor of the provided DN, or false if not.

Throws:

LDAPException - If the provided string cannot be parsed as a DN.

isAncestorOf

public static boolean isAncestorOf(@NotNull
                                   java.lang.String s1,
                                   @NotNull
                                   java.lang.String s2,
                                   boolean allowEquals)
                            throws LDAPException

Indicates whether the DN represented by the first string is an ancestor of the DN represented by the second string. The first DN will be considered an ancestor of the second DN if the array of RDN components for the first DN ends with the elements that comprise the array of RDN components for the second DN (i.e., if the first DN is subordinate to, or optionally equal to, the second DN). The null DN will be considered an ancestor for all other DNs (with the exception of the null DN if allowEquals is false).

Parameters:

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.

Returns:

true if the first DN may be considered an ancestor of the second DN, or false if not.

Throws:

LDAPException - If either of the provided strings cannot be parsed as a DN.

isDescendantOf

public boolean isDescendantOf(@NotNull
                              DN dn,
                              boolean allowEquals)

Indicates whether this DN is a descendant of the provided DN. It will be considered a descendant of the provided DN if the array of RDN components for this DN ends with the elements that comprise the RDN components for the provided DN (i.e., if this DN is subordinate to, or optionally equal to, the provided DN). The null DN will not be considered a descendant for any other DNs (with the exception of the null DN if allowEquals is true).

Parameters:

dn - The DN for which to make the determination.

allowEquals - Indicates whether a DN should be considered a descendant of itself.

Returns:

true if this DN may be considered a descendant of the provided DN, or false if not.

isDescendantOf

public boolean isDescendantOf(@NotNull
                              java.lang.String s,
                              boolean allowEquals)
                       throws LDAPException

Indicates whether this DN is a descendant of the DN with the provided string representation. It will be considered a descendant of the provided DN if the array of RDN components for this DN ends with the elements that comprise the RDN components for the provided DN (i.e., if this DN is subordinate to, or optionally equal to, the provided DN). The null DN will not be considered a descendant for any other DNs (with the exception of the null DN if allowEquals is true).

Parameters:

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.

Returns:

true if this DN may be considered a descendant of the provided DN, or false if not.

Throws:

LDAPException - If the provided string cannot be parsed as a DN.

isDescendantOf

public static boolean isDescendantOf(@NotNull
                                     java.lang.String s1,
                                     @NotNull
                                     java.lang.String s2,
                                     boolean allowEquals)
                              throws LDAPException

Indicates whether the DN represented by the first string is a descendant of the DN represented by the second string. The first DN will be considered a descendant of the second DN if the array of RDN components for the first DN ends with the elements that comprise the RDN components for the second DN (i.e., if the first DN is subordinate to, or optionally equal to, the second DN). The null DN will not be considered a descendant for any other DNs (with the exception of the null DN if allowEquals is true).

Parameters:

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.

Returns:

true if this DN may be considered a descendant of the provided DN, or false if not.

Throws:

LDAPException - If either of the provided strings cannot be parsed as a DN.

matchesBaseAndScope

public boolean matchesBaseAndScope(@NotNull
                                   java.lang.String baseDN,
                                   @NotNull
                                   SearchScope scope)
                            throws LDAPException

Indicates whether this DN falls within the range of the provided search base DN and scope.

Parameters:

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.

Returns:

true if this DN is within the range of the provided base and scope, or false if not.

Throws:

LDAPException - If a problem occurs while making the determination.

matchesBaseAndScope

public boolean matchesBaseAndScope(@NotNull
                                   DN baseDN,
                                   @NotNull
                                   SearchScope scope)
                            throws LDAPException

Indicates whether this DN falls within the range of the provided search base DN and scope.

Parameters:

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.

Returns:

true if this DN is within the range of the provided base and scope, or false if not.

Throws:

LDAPException - If a problem occurs while making the determination.

hashCode

public int hashCode()

Generates a hash code for this DN.

Overrides:

hashCode in class java.lang.Object

Returns:

The generated hash code for this DN.

equals

public boolean equals(@Nullable
                      java.lang.Object o)

Indicates whether the provided object is equal to this DN. In order for the provided object to be considered equal, it must be a non-null DN with the same set of RDN components.

Specified by:

equals in interface java.util.Comparator<DN>

Overrides:

equals in class java.lang.Object

Parameters:

o - The object for which to make the determination.

Returns:

true if the provided object is considered equal to this DN, or false if not.

equals

public boolean equals(@Nullable
                      java.lang.String s)
               throws LDAPException

Indicates whether the DN with the provided string representation is equal to this DN.

Parameters:

s - The string representation of the DN to compare with this DN.

Returns:

true if the DN with the provided string representation is equal to this DN, or false if not.

Throws:

LDAPException - If the provided string cannot be parsed as a DN.

equals

public static boolean equals(@NotNull
                             java.lang.String s1,
                             @NotNull
                             java.lang.String s2)
                      throws LDAPException

Indicates whether the two provided strings represent the same DN.

Parameters:

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.

Returns:

true if the provided strings represent the same DN, or false if not.

Throws:

LDAPException - If either of the provided strings cannot be parsed as a DN.

equals

public static boolean equals(@NotNull
                             java.lang.String s1,
                             @NotNull
                             java.lang.String s2,
                             @Nullable
                             Schema schema)
                      throws LDAPException

Indicates whether the two provided strings represent the same DN.

Parameters:

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.

schema - The schema to use while making the determination. It may be null if no schema is available.

Returns:

true if the provided strings represent the same DN, or false if not.

Throws:

LDAPException - If either of the provided strings cannot be parsed as a DN.

getDNEscapingStrategy

@NotNull
public static DNEscapingStrategy getDNEscapingStrategy()

Retrieves the escaping strategy that should be used by default when constructing the string representations of DNs and RDNs.

Returns:

The escaping strategy that should be used by default when constructing the string representations of DNs and RDNs.

setDNEscapingStrategy

public static void setDNEscapingStrategy(@NotNull
                                         DNEscapingStrategy dnEscapingStrategy)

Specifies the escaping strategy that should be used by default when constructing the string representations of DNs and RDNs.

Parameters:

dnEscapingStrategy - The escaping strategy that should be used by default when constructing the string representations of DNs and RDNs. It must not be null.

toString

@NotNull
public java.lang.String toString()

Retrieves a string representation of this DN.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this DN.

toMinimallyEncodedString

@NotNull
public java.lang.String toMinimallyEncodedString()

Retrieves a string representation of this DN with minimal encoding for special characters. Only those characters specified in RFC 4514 section 2.4 will be escaped. No escaping will be used for non-ASCII characters or non-printable ASCII characters.

Returns:

A string representation of this DN with minimal encoding for special characters.

toString

public void toString(@NotNull
                     java.lang.StringBuilder buffer)

Appends a string representation of this DN to the provided buffer.

Parameters:

buffer - The buffer to which to append the string representation of this DN.

toString

public void toString(@NotNull
                     java.lang.StringBuilder buffer,
                     boolean minimizeEncoding)

Appends a string representation of this DN to the provided buffer.

Parameters:

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.

toString

public void toString(@NotNull
                     ByteStringBuffer buffer,
                     @NotNull
                     DNEscapingStrategy escapingStrategy)

Appends a string representation of this DN to the provided buffer.

Parameters:

buffer - The buffer to which the string representation is to be appended. It must not be null.

escapingStrategy - The strategy to use to determine which types of optional escaping should be used for values. It must not be null.

toNormalizedString

@NotNull
public java.lang.String toNormalizedString()

Retrieves a normalized string representation of this DN.

Returns:

A normalized string representation of this DN.

toNormalizedString

public void toNormalizedString(@NotNull
                               java.lang.StringBuilder buffer)

Appends a normalized string representation of this DN to the provided buffer.

Parameters:

buffer - The buffer to which to append the normalized string representation of this DN.

normalize

@NotNull
public static java.lang.String normalize(@NotNull
                                                  java.lang.String s)
                                           throws LDAPException

Retrieves a normalized representation of the DN with the provided string representation.

Parameters:

s - The string representation of the DN to normalize. It must not be null.

Returns:

The normalized representation of the DN with the provided string representation.

Throws:

LDAPException - If the provided string cannot be parsed as a DN.

normalize

@NotNull
public static java.lang.String normalize(@NotNull
                                                  java.lang.String s,
                                                  @Nullable
                                                  Schema schema)
                                           throws LDAPException

Retrieves a normalized representation of the DN with the provided string representation.

Parameters:

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.

Returns:

The normalized representation of the DN with the provided string representation.

Throws:

LDAPException - If the provided string cannot be parsed as a DN.

compareTo

public int compareTo(@NotNull
                     DN dn)

Compares the provided DN to this DN to determine their relative order in a sorted list.

Specified by:

compareTo in interface java.lang.Comparable<DN>

Parameters:

dn - The DN to compare against this DN. It must not be null.

Returns:

A negative integer if this DN should come before the provided DN in a sorted list, a positive integer if this DN should come after the provided DN in a sorted list, or zero if the provided DN can be considered equal to this DN.

compare

public int compare(@NotNull
                   DN dn1,
                   @NotNull
                   DN dn2)

Compares the provided DN values to determine their relative order in a sorted list.

Specified by:

compare in interface java.util.Comparator<DN>

Parameters:

dn1 - The first DN to be compared. It must not be null.

dn2 - The second DN to be compared. It must not be null.

Returns:

A negative integer if the first DN should come before the second DN in a sorted list, a positive integer if the first DN should come after the second DN in a sorted list, or zero if the two DN values can be considered equal.

compare

public static int compare(@NotNull
                          java.lang.String s1,
                          @NotNull
                          java.lang.String s2)
                   throws LDAPException

Compares the DNs with the provided string representations to determine their relative order in a sorted list.

Parameters:

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.

Returns:

A negative integer if the first DN should come before the second DN in a sorted list, a positive integer if the first DN should come after the second DN in a sorted list, or zero if the two DN values can be considered equal.

Throws:

LDAPException - If either of the provided strings cannot be parsed as a DN.

compare

public static int compare(@NotNull
                          java.lang.String s1,
                          @NotNull
                          java.lang.String s2,
                          @Nullable
                          Schema schema)
                   throws LDAPException

Compares the DNs with the provided string representations to determine their relative order in a sorted list.

Parameters:

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.

Returns:

A negative integer if the first DN should come before the second DN in a sorted list, a positive integer if the first DN should come after the second DN in a sorted list, or zero if the two DN values can be considered equal.

Throws:

LDAPException - If either of the provided strings cannot be parsed as a DN.

getDNRelativeToBaseDN

@NotNull
public static java.lang.String getDNRelativeToBaseDN(@NotNull
                                                              java.lang.String fullDN,
                                                              @NotNull
                                                              java.lang.String baseDN)
                                                       throws LDAPException

Retrieves a string that represents the portion of the provided full DN that is relative to the given base DN (that is, the full DN with the base DN stripped off). For example, if the provided full DN is "uid=jdoe,ou=People,dc=example,dc=com" and the base DN is "dc=example,dc=com", then the returned DN will be "uid=jdoe,ou=People".

Parameters:

fullDN - The full DN for which to obtain the portion relative to the base DN. It must not be null, and it must represent a valid DN that is a descendant of or equal to the base DN.

baseDN - The base DN to strip off of the provided full DN. It must not be null, and it must be an ancestor of or equal to the full DN.

Returns:

A string representation of the DN that represents the portion of the full DN that is relative to the base DN, an empty string if the full DN is equal to the base DN, or the provided full DN if the base DN represents the null DN.

Throws:

LDAPException - If either of the provided strings is not a valid DN, or if the provided full DN is not an ancestor of or equal to the given base DN.

getDNRelativeToBaseDN

@NotNull
public static DN getDNRelativeToBaseDN(@NotNull
                                                DN fullDN,
                                                @NotNull
                                                DN baseDN)
                                         throws LDAPException

Retrieves a portion of the provided full DN that is relative to the given base DN (that is, the full DN with the base DN stripped off). For example, if the provided full DN is "uid=jdoe,ou=People,dc=example,dc=com" and the base DN is "dc=example,dc=com", then the returned DN will be "uid=jdoe,ou=People".

Parameters:

fullDN - The full DN for which to obtain the portion relative to the base DN. It must not be null, and it must be a descendant of or equal to the base DN.

baseDN - The base DN to strip off of the provided full DN. It must not be null, and it must be an ancestor of or equal to the full DN.

Returns:

A DN that represents the portion of the full DN that is relative to the base DN, NULL_DN if the full DN is equal to the base DN, or the provided full DN if the base DN is the null DN.

Throws:

LDAPException - If the provided full DN is not an ancestor of or equal to the given base DN.