org.apache.directory.shared.ldap.name
Class DN

java.lang.Object
  extended by org.apache.directory.shared.ldap.name.DN
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<DN>, java.lang.Iterable<RDN>

public class DN
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable, java.lang.Comparable<DN>, java.lang.Iterable<RDN>

The DN class contains a DN (Distinguished Name). Its specification can be found in RFC 2253, "UTF-8 String Representation of Distinguished Names". We will store two representation of a DN : - a user Provider representation, which is the parsed String given by a user - an internal representation. A DN is formed of RDNs, in a specific order : RDN[n], RDN[n-1], ... RDN[1], RDN[0] It represents a tree, in which the root is the last RDN (RDN[0]) and the leaf is the first RDN (RDN[n]).

Version:
$Rev: 930282 $, $Date: 2010-04-02 16:29:58 +0200 (Fri, 02 Apr 2010) $
Author:
Apache Directory Project
See Also:
Serialized Form

Field Summary
static DN EMPTY_DN
          A null DN
static int EQUAL
          Value returned by the compareTo method if values are equals
protected static org.slf4j.Logger LOG
          The LoggerFactory used by this class
static int NOT_EQUAL
          Value returned by the compareTo method if values are not equals
protected  java.util.List<RDN> rdns
          The RDNs that are elements of the DN NOTE THAT THESE ARE IN THE OPPOSITE ORDER FROM THAT IMPLIED BY THE JAVADOC! Rdn[0] is rdns.get(n) and Rdn[n] is rdns.get(0)
 
Constructor Summary
DN()
          Construct an empty DN object
DN(DN dn)
          Copies a DN to an DN.
DN(java.lang.String... upRdns)
          Creates a new instance of DN, using varargs to declare the RDNs.
DN(java.lang.String upName)
          Parse a String and checks that it is a valid DN
 
Method Summary
 DN add(int pos, RDN newRdn)
          Adds a single RDN to a specific position.
 DN add(int posn, java.lang.String comp)
          
 DN add(RDN newRdn)
          Adds a single RDN to the (leaf) end of this name.
 DN add(java.lang.String comp)
          
 DN addAll(DN suffix)
          
 DN addAll(int posn, DN dn)
          
 DN addAll(int posn, javax.naming.Name name)
          
 DN addAllNormalized(int posn, DN name)
          Adds the components of a name -- in order -- at a specified position within this name.
 DN addNormalized(RDN newRdn)
          Adds a single normalized RDN to the (leaf) end of this name.
 java.lang.Object clone()
          
 int compareTo(DN dn)
          
 boolean equals(java.lang.Object obj)
           
static DN fromName(javax.naming.Name name)
          Convert a Name to a DN
 java.lang.String get(int posn)
          Get the given RDN as a String.
 java.util.Enumeration<RDN> getAllRdn()
          Retrieves the components of this name as an enumeration of strings.
static byte[] getBytes(DN dn)
          Get an UTF-8 representation of the normalized form of the DN
 java.lang.String getName()
          Get the initial DN
static int getNbBytes(DN dn)
          Get the number of bytes necessary to store this DN
 java.lang.String getNormName()
          Get the normalized DN
 DN getPrefix(int posn)
          
 RDN getRdn()
          Retrieves the last (leaf) component of this name.
 RDN getRdn(int posn)
          Retrieves a component of this name.
 java.util.List<RDN> getRdns()
          Retrieves all the components of this name.
 DN getSuffix(int posn)
          
 int hashCode()
          Gets the hash code of this name.
 boolean hasSuffix(DN dn)
          Determines whether this name has a specific suffix.
 boolean isChildOf(DN dn)
          Tells if a DN is a child of another DN.
For instance, dc=example, dc=com is a child of dc=com
 boolean isChildOf(java.lang.String dn)
          Tells if a DN is a child of another DN.
For instance, dc=example, dc=com is a child of dc=com
 boolean isEmpty()
          return true if this DN contains no RDNs
 boolean isNormalized()
          Tells if the DN has already been normalized or not
 boolean isParentOf(DN dn)
          Tells if the current DN is a parent of another DN.
For instance, dc=com is a parent of dc=example, dc=com
 boolean isParentOf(java.lang.String dn)
          Tells if the current DN is a parent of another DN.
For instance, dc=com is a parent of dc=example, dc=com
static boolean isValid(java.lang.String dn)
          Check if a DistinguishedName is syntactically valid.
 java.util.Iterator<RDN> iterator()
          
static DN normalize(DN dn, java.util.Map<java.lang.String,OidNormalizer> oidsMap)
          Change the internal DN, using the OID instead of the first name or other aliases.
 DN normalize(java.util.Map<java.lang.String,OidNormalizer> oidsMap)
          Change the internal DN, using the OID instead of the first name or other aliases.
static DN normalize(java.lang.String name, java.util.Map<java.lang.String,OidNormalizer> oidsMap)
          Static factory which creates a normalized DN from a String and a Map of OIDs.
 void readExternal(java.io.ObjectInput in)
           
 RDN remove(int posn)
          
 int size()
          
static javax.naming.Name toName(DN dn)
          Convert a DN to a Name
 java.lang.String toString()
          Return the normalized DN as a String.
 void writeExternal(java.io.ObjectOutput out)
           
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

LOG

protected static final org.slf4j.Logger LOG
The LoggerFactory used by this class


NOT_EQUAL

public static final int NOT_EQUAL
Value returned by the compareTo method if values are not equals

See Also:
Constant Field Values

EQUAL

public static final int EQUAL
Value returned by the compareTo method if values are equals

See Also:
Constant Field Values

rdns

protected java.util.List<RDN> rdns
The RDNs that are elements of the DN NOTE THAT THESE ARE IN THE OPPOSITE ORDER FROM THAT IMPLIED BY THE JAVADOC! Rdn[0] is rdns.get(n) and Rdn[n] is rdns.get(0)


EMPTY_DN

public static final DN EMPTY_DN
A null DN

Constructor Detail

DN

public DN()
Construct an empty DN object


DN

public DN(DN dn)
   throws LdapInvalidDnException
Copies a DN to an DN.

Parameters:
name - composed of String name components.
Throws:
LdapInvalidDnException - If the Name is invalid.

DN

public DN(java.lang.String upName)
   throws LdapInvalidDnException
Parse a String and checks that it is a valid DN

<distinguishedName> ::= <name> | e
<name> ::= <name-component> <name-components>
<name-components> ::= <spaces> <separator> <spaces> <name-component> <name-components> | e

Parameters:
upName - The String that contains the DN.
Throws:
LdapInvalidNameException - if the String does not contain a valid DN.
LdapInvalidDnException

DN

public DN(java.lang.String... upRdns)
   throws LdapInvalidDnException
Creates a new instance of DN, using varargs to declare the RDNs. Each String is either a full RDN, or a couple of AttributeType DI and a value. If the String contains a '=' symbol, the the constructor will assume that the String arg contains afull RDN, otherwise, it will consider that the following arg is the value. An example of usage would be :
 String exampleName = "example";
 String baseDn = "dc=apache,dc=org";
 
 DN dn = new DN(
     "cn=Test",
     "ou", exampleName,
     baseDn);
 

Parameters:
upNames -
Throws:
LdapInvalidDnException
Method Detail

normalize

public static DN normalize(java.lang.String name,
                           java.util.Map<java.lang.String,OidNormalizer> oidsMap)
                    throws LdapInvalidDnException
Static factory which creates a normalized DN from a String and a Map of OIDs.

Parameters:
name - The DN as a String
oidsMap - The OID mapping
Returns:
A valid DN
Throws:
LdapInvalidNameException - If the DN is invalid.
LdapInvalidDnException - If something went wrong.

toString

public java.lang.String toString()
Return the normalized DN as a String. It returns the same value as the getNormName method

Overrides:
toString in class java.lang.Object
Returns:
A String representing the normalized DN

hashCode

public int hashCode()
Gets the hash code of this name.

Overrides:
hashCode in class java.lang.Object
Returns:
the instance hash code
See Also:
Object.hashCode()

getName

public java.lang.String getName()
Get the initial DN

Returns:
The DN as a String

getNormName

public java.lang.String getNormName()
Get the normalized DN

Returns:
The DN as a String

size

public int size()


getNbBytes

public static int getNbBytes(DN dn)
Get the number of bytes necessary to store this DN

Parameters:
dn - The DN.
Returns:
A integer, which is the size of the UTF-8 byte array

getBytes

public static byte[] getBytes(DN dn)
Get an UTF-8 representation of the normalized form of the DN

Parameters:
dn - The DN.
Returns:
A byte[] representation of the DN

isParentOf

public boolean isParentOf(java.lang.String dn)
Tells if the current DN is a parent of another DN.
For instance, dc=com is a parent of dc=example, dc=com

Parameters:
dn - The child
Returns:
true if the current DN is a parent of the given DN

isParentOf

public boolean isParentOf(DN dn)
Tells if the current DN is a parent of another DN.
For instance, dc=com is a parent of dc=example, dc=com

Parameters:
dn - The child
Returns:
true if the current DN is a parent of the given DN

isChildOf

public boolean isChildOf(java.lang.String dn)
Tells if a DN is a child of another DN.
For instance, dc=example, dc=com is a child of dc=com

Parameters:
dn - The parent
Returns:
true if the current DN is a child of the given DN

isChildOf

public boolean isChildOf(DN dn)
Tells if a DN is a child of another DN.
For instance, dc=example, dc=com is a child of dc=com

Parameters:
dn - The parent
Returns:
true if the current DN is a child of the given DN

hasSuffix

public boolean hasSuffix(DN dn)
Determines whether this name has a specific suffix. A name name has a DN as a suffix if its right part contains the given DN Be aware that for a specific DN like : cn=xxx, ou=yyy the hasSuffix method will return false with ou=yyy, and true with cn=xxx

Parameters:
dn - the name to check
Returns:
true if dn is a suffix of this name, false otherwise

isEmpty

public boolean isEmpty()
return true if this DN contains no RDNs


get

public java.lang.String get(int posn)
Get the given RDN as a String. The position is used in the reverse order. Assuming that we have a DN like
dc=example,dc=apache,dc=org
then :
  • get(0) will return dc=org
  • get(1) will return dc=apache
  • get(2) will return dc=example
  • Parameters:
    posn - The position of the wanted RDN in the DN.

    getRdn

    public RDN getRdn(int posn)
    Retrieves a component of this name.

    Parameters:
    posn - the 0-based index of the component to retrieve. Must be in the range [0,size()).
    Returns:
    the component at index posn
    Throws:
    java.lang.ArrayIndexOutOfBoundsException - if posn is outside the specified range

    getRdn

    public RDN getRdn()
    Retrieves the last (leaf) component of this name.

    Returns:
    the last component of this DN

    getRdns

    public java.util.List<RDN> getRdns()
    Retrieves all the components of this name.

    Returns:
    All the components

    getAllRdn

    public java.util.Enumeration<RDN> getAllRdn()
    Retrieves the components of this name as an enumeration of strings. The effect on the enumeration of updates to this name is undefined. If the name has zero components, an empty (non-null) enumeration is returned. This starts at the root (rightmost) rdn.

    Returns:
    an enumeration of the components of this name, as Rdn

    getPrefix

    public DN getPrefix(int posn)


    getSuffix

    public DN getSuffix(int posn)


    addAllNormalized

    public DN addAllNormalized(int posn,
                               DN name)
                        throws LdapInvalidDnException
    Adds the components of a name -- in order -- at a specified position within this name. Components of this name at or after the index of the first new component are shifted up (away from 0) to accommodate the new components. Compoenents are supposed to be normalized.

    Parameters:
    posn - the index in this name at which to add the new components. Must be in the range [0,size()]. Note this is from the opposite end as rnds.get(posn)
    name - the components to add
    Returns:
    the updated name (not a new one)
    Throws:
    java.lang.ArrayIndexOutOfBoundsException - if posn is outside the specified range
    LdapInvalidDnException - if n is not a valid name, or if the addition of the components would violate the syntax rules of this name

    addAll

    public DN addAll(DN suffix)
              throws LdapInvalidDnException

    Throws:
    LdapInvalidDnException

    addAll

    public DN addAll(int posn,
                     javax.naming.Name name)
              throws javax.naming.InvalidNameException,
                     LdapInvalidDnException

    Throws:
    javax.naming.InvalidNameException
    LdapInvalidDnException

    addAll

    public DN addAll(int posn,
                     DN dn)
              throws LdapInvalidDnException

    Throws:
    LdapInvalidDnException

    add

    public DN add(java.lang.String comp)
           throws LdapInvalidDnException

    Throws:
    LdapInvalidDnException

    add

    public DN add(RDN newRdn)
    Adds a single RDN to the (leaf) end of this name.

    Parameters:
    newRdn - the RDN to add
    Returns:
    the updated name (not a new one)

    add

    public DN add(int pos,
                  RDN newRdn)
    Adds a single RDN to a specific position.

    Parameters:
    newRdn - the RDN to add
    pos - The position where we want to add the Rdn
    Returns:
    the updated name (not a new one)

    addNormalized

    public DN addNormalized(RDN newRdn)
    Adds a single normalized RDN to the (leaf) end of this name.

    Parameters:
    newRdn - the RDN to add
    Returns:
    the updated name (not a new one)

    add

    public DN add(int posn,
                  java.lang.String comp)
           throws LdapInvalidDnException

    Throws:
    LdapInvalidDnException

    remove

    public RDN remove(int posn)
               throws LdapInvalidDnException

    Throws:
    LdapInvalidDnException

    clone

    public java.lang.Object clone()

    Overrides:
    clone in class java.lang.Object

    equals

    public boolean equals(java.lang.Object obj)
    Overrides:
    equals in class java.lang.Object
    Returns:
    true if the two instances are equals
    See Also:
    Object.equals(java.lang.Object)

    compareTo

    public int compareTo(DN dn)

    Specified by:
    compareTo in interface java.lang.Comparable<DN>

    normalize

    public static DN normalize(DN dn,
                               java.util.Map<java.lang.String,OidNormalizer> oidsMap)
                        throws LdapInvalidDnException
    Change the internal DN, using the OID instead of the first name or other aliases. As we still have the UP name of each RDN, we will be able to provide both representation of the DN. example : dn: 2.5.4.3=People, dc=example, domainComponent=com will be transformed to : 2.5.4.3=People, 0.9.2342.19200300.100.1.25=example, 0.9.2342.19200300.100.1.25=com because 2.5.4.3 is the OID for cn and dc is the first alias of the couple of aliases (dc, domaincomponent), which OID is 0.9.2342.19200300.100.1.25. This is really important do have such a representation, as 'cn' and 'commonname' share the same OID.

    Parameters:
    dn - The DN to transform.
    oidsMap - The mapping between names and oids.
    Returns:
    A normalized form of the DN.
    Throws:
    LdapInvalidDnException - If something went wrong.

    normalize

    public DN normalize(java.util.Map<java.lang.String,OidNormalizer> oidsMap)
                 throws LdapInvalidDnException
    Change the internal DN, using the OID instead of the first name or other aliases. As we still have the UP name of each RDN, we will be able to provide both representation of the DN. example : dn: 2.5.4.3=People, dc=example, domainComponent=com will be transformed to : 2.5.4.3=People, 0.9.2342.19200300.100.1.25=example, 0.9.2342.19200300.100.1.25=com because 2.5.4.3 is the OID for cn and dc is the first alias of the couple of aliases (dc, domaincomponent), which OID is 0.9.2342.19200300.100.1.25. This is really important do have such a representation, as 'cn' and 'commonname' share the same OID.

    Parameters:
    oidsMap - The mapping between names and oids.
    Returns:
    The normalized DN
    Throws:
    LdapInvalidDnException - If something went wrong.

    isValid

    public static boolean isValid(java.lang.String dn)
    Check if a DistinguishedName is syntactically valid.

    Parameters:
    dn - The DN to validate
    Returns:
    true> if the DN is valid, false otherwise

    isNormalized

    public boolean isNormalized()
    Tells if the DN has already been normalized or not

    Returns:
    true if the DN is already normalized.

    writeExternal

    public void writeExternal(java.io.ObjectOutput out)
                       throws java.io.IOException
    Parameters:
    out - The stream in which the DN will be serialized
    Throws:
    java.io.IOException - If the serialization fail
    See Also:
    We have to store a DN data efficiently. Here is the structure :
  • upName
  • The User provided DN

  • normName
  • May be null if the normName is equaivalent to the upName

  • rdns
  • The rdn's List.

    for each rdn :

  • call the RDN write method

  • readExternal

    public void readExternal(java.io.ObjectInput in)
                      throws java.io.IOException,
                             java.lang.ClassNotFoundException
    Parameters:
    in - The stream from which the DN is read
    Throws:
    java.io.IOException - If the stream can't be read
    java.lang.ClassNotFoundException - If the RDN can't be created
    See Also:
    We read back the data to create a new DN. The structure read is exposed in the {@link DN#writeExternal(ObjectOutput)} method


    fromName

    public static DN fromName(javax.naming.Name name)
    Convert a Name to a DN

    Parameters:
    name - The Name to convert
    Returns:
    A DN

    toName

    public static javax.naming.Name toName(DN dn)
    Convert a DN to a Name

    Parameters:
    name - The DN to convert
    Returns:
    A Name

    iterator

    public java.util.Iterator<RDN> iterator()

    Specified by:
    iterator in interface java.lang.Iterable<RDN>


    Copyright © 2003-2011 Apache Software Foundation. All Rights Reserved.