org.opends.server.types
Class DN

java.lang.Object
  extended by org.opends.server.types.DN
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<DN>
Direct Known Subclasses:
LazyDN

@PublicAPI(stability=UNCOMMITTED,
           mayInstantiate=true,
           mayExtend=false,
           mayInvoke=true)
public class DN
extends java.lang.Object
implements java.lang.Comparable<DN>, java.io.Serializable

This class defines a data structure for storing and interacting with the distinguished names associated with entries in the Directory Server.

See Also:
Serialized Form

Field Summary
static DN NULL_DN
          A singleton instance of the null DN (a DN with no components).
 
Constructor Summary
DN()
          Creates a new DN with no RDN components (i.e., a null DN or root DSE).
DN(java.util.List<RDN> rdnComponents)
          Creates a new DN with the provided set of RDNs, arranged with the suffix as the last element.
DN(RDN[] rdnComponents)
          Creates a new DN with the provided set of RDNs, arranged with the suffix as the last element.
DN(RDN rdn, DN parentDN)
          Creates a new DN with the given RDN below the specified parent.
 
Method Summary
 int compareTo(DN dn)
          Compares this DN with the provided DN based on a natural order.
 DN concat(DN relativeBaseDN)
          Creates a new DN that is a descendant of this DN, using the specified DN as a relative base DN.
 DN concat(RDN rdn)
          Creates a new DN that is a child of this DN, using the specified RDN.
 DN concat(RDN[] rdnComponents)
          Creates a new DN that is a descendant of this DN, using the specified RDN components.
static DN decode(ByteString dnString)
          Decodes the provided ASN.1 octet string as a DN.
static DN decode(java.lang.String dnString)
          Decodes the provided string as a DN.
 boolean equals(java.lang.Object o)
          Indicates whether the provided object is equal to this DN.
 int getNumComponents()
          Retrieves the number of RDN components for this DN.
 DN getParent()
          Retrieves the DN of the entry that is the immediate parent for this entry.
 DN getParentDNInSuffix()
          Retrieves the DN of the entry that is the immediate parent for this entry.
 RDN getRDN()
          Retrieves the outermost RDN component for this DN (i.e., the one that is furthest from the suffix).
 RDN getRDN(int pos)
          Retrieves the RDN component at the specified position in the set of components for this DN.
 int hashCode()
          Retrieves the hash code for this DN.
 boolean isAncestorOf(DN dn)
          Indicates whether this DN is an ancestor of the provided DN (i.e., that the RDN components of this DN are the same as the last RDN components for the provided DN).
 boolean isDescendantOf(DN dn)
          Indicates whether this DN is a descendant of the provided DN (i.e., that the RDN components of the provided DN are the same as the last RDN components for this DN).
 boolean isNullDN()
          Indicates whether this represents a null DN.
 boolean matchesBaseAndScope(DN baseDN, SearchScope scope)
          Indicates whether this entry falls within the range of the provided search base DN and scope.
static DN nullDN()
          Retrieves a singleton instance of the null DN.
 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.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

NULL_DN

public static DN NULL_DN
A singleton instance of the null DN (a DN with no components).

Constructor Detail

DN

public DN()
Creates a new DN with no RDN components (i.e., a null DN or root DSE).


DN

public DN(RDN[] rdnComponents)
Creates a new DN with the provided set of RDNs, arranged with the suffix as the last element.

Parameters:
rdnComponents - The set of RDN components that make up this DN.

DN

public DN(java.util.List<RDN> rdnComponents)
Creates a new DN with the provided set of RDNs, arranged with the suffix as the last element.

Parameters:
rdnComponents - The set of RDN components that make up this DN.

DN

public DN(RDN rdn,
          DN parentDN)
Creates a new DN with the given RDN below the specified parent.

Parameters:
rdn - The RDN to use for the new DN. It must not be null.
parentDN - The DN of the entry below which the new DN should exist. It must not be null.
Method Detail

nullDN

public static DN nullDN()
Retrieves a singleton instance of the null DN.

Returns:
A singleton instance of the null DN.

isNullDN

public boolean isNullDN()
Indicates whether this represents a null DN. This could target the root DSE for the Directory Server, or the authorization DN for an anonymous or unauthenticated client.

Returns:
true if this does represent a null DN, or false if it does not.

getNumComponents

public int getNumComponents()
Retrieves the number of RDN components for this DN.

Returns:
The number of RDN components for this DN.

getRDN

public RDN getRDN()
Retrieves the outermost RDN component for this DN (i.e., the one that is furthest from the suffix).

Returns:
The outermost RDN component for this DN, or null if there are no RDN components in the DN.

getRDN

public RDN getRDN(int pos)
Retrieves the RDN component at the specified position in the set of components for this DN.

Parameters:
pos - The position of the RDN component to retrieve.
Returns:
The RDN component at the specified position in the set of components for this DN.

getParent

public DN getParent()
Retrieves the DN of the entry that is the immediate parent for this entry. Note that this method does not take the server's naming context configuration into account when making the determination.

Returns:
The DN of the entry that is the immediate parent for this entry, or null if the entry with this DN does not have a parent.

getParentDNInSuffix

public DN getParentDNInSuffix()
Retrieves the DN of the entry that is the immediate parent for this entry. This method does take the server's naming context configuration into account, so if the current DN is a naming context for the server, then it will not be considered to have a parent.

Returns:
The DN of the entry that is the immediate parent for this entry, or null if the entry with this DN does not have a parent (either because there is only a single RDN component or because this DN is a suffix defined in the server).

concat

public DN concat(RDN rdn)
Creates a new DN that is a child of this DN, using the specified RDN.

Parameters:
rdn - The RDN for the child of this DN.
Returns:
A new DN that is a child of this DN, using the specified RDN.

concat

public DN concat(RDN[] rdnComponents)
Creates a new DN that is a descendant of this DN, using the specified RDN components.

Parameters:
rdnComponents - The RDN components for the descendant of this DN.
Returns:
A new DN that is a descendant of this DN, using the specified RDN components.

concat

public DN concat(DN relativeBaseDN)
Creates a new DN that is a descendant of this DN, using the specified DN as a relative base DN. That is, the resulting DN will first have the components of the provided DN followed by the components of this DN.

Parameters:
relativeBaseDN - The relative base DN to concatenate onto this DN.
Returns:
A new DN that is a descendant of this DN, using the specified DN as a relative base DN.

isDescendantOf

public boolean isDescendantOf(DN dn)
Indicates whether this DN is a descendant of the provided DN (i.e., that the RDN components of the provided DN are the same as the last RDN components for this DN). Note that if this DN equals the provided DN it is still considered to be a descendant of the provided DN by this method as both then reside within the same subtree.

Parameters:
dn - The DN for which to make the determination.
Returns:
true if this DN is a descendant of the provided DN, or false if not.

isAncestorOf

public boolean isAncestorOf(DN dn)
Indicates whether this DN is an ancestor of the provided DN (i.e., that the RDN components of this DN are the same as the last RDN components for the provided DN).

Parameters:
dn - The DN for which to make the determination.
Returns:
true if this DN is an ancestor of the provided DN, or false if not.

matchesBaseAndScope

public boolean matchesBaseAndScope(DN baseDN,
                                   SearchScope scope)
Indicates whether this entry falls within the range of the provided search base DN and scope.

Parameters:
baseDN - The base DN for which to make the determination.
scope - The search scope for which to make the determination.
Returns:
true if this entry is within the given base and scope, or false if it is not.

decode

public static DN decode(ByteString dnString)
                 throws DirectoryException
Decodes the provided ASN.1 octet string as a DN.

Parameters:
dnString - The ASN.1 octet string to decode as a DN.
Returns:
The decoded DN.
Throws:
DirectoryException - If a problem occurs while trying to decode the provided ASN.1 octet string as a DN.

decode

public static DN decode(java.lang.String dnString)
                 throws DirectoryException
Decodes the provided string as a DN.

Parameters:
dnString - The string to decode as a DN.
Returns:
The decoded DN.
Throws:
DirectoryException - If a problem occurs while trying to decode the provided string as a DN.

equals

public boolean equals(java.lang.Object o)
Indicates whether the provided object is equal to this DN. In order for the object to be considered equal, it must be a DN with the same number of RDN components and each corresponding RDN component must be equal.

Overrides:
equals in class java.lang.Object
Parameters:
o - The object for which to make the determination.
Returns:
true if the provided object is a DN that is equal to this DN, or false if it is not.

hashCode

public int hashCode()
Retrieves the hash code for this DN. The hash code will be the sum of the hash codes for all the RDN components.

Overrides:
hashCode in class java.lang.Object
Returns:
The hash code for this DN.

toString

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.

toString

public void toString(java.lang.StringBuilder buffer)
Appends a string representation of this DN to the provided buffer.

Parameters:
buffer - The buffer to which the information should be appended.

toNormalizedString

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(java.lang.StringBuilder buffer)
Appends a normalized string representation of this DN to the provided buffer.

Parameters:
buffer - The buffer to which the information should be appended.

compareTo

public int compareTo(DN dn)
Compares this DN with the provided DN based on a natural order. This order will be first hierarchical (ancestors will come before descendants) and then alphabetical by attribute name(s) and value(s).

Specified by:
compareTo in interface java.lang.Comparable<DN>
Parameters:
dn - The DN against which to compare this DN.
Returns:
A negative integer if this DN should come before the provided DN, a positive integer if this DN should come after the provided DN, or zero if there is no difference with regard to ordering.