Package org.apache.directory.api.ldap.model.name

Class Dn

  • All Implemented Interfaces:
    Externalizable, Serializable, Iterable<Rdn>
    public class Dn
extends Object
implements Iterable<Rdn>, Externalizable
    The Dn class contains a Dn (Distinguished Name). This class is immutable.
    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 position in a hierarchy, in which the root is the last Rdn (Rdn[0]) and the leaf is the first Rdn (Rdn[n]).
    Author:
    Apache Directory Project
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Dn EMPTY_DN
      A null Dn
      static int EQUAL
      Value returned by the compareTo method if values are equals
      protected static Logger LOG
      The LoggerFactory used by this class
      static int NOT_EQUAL
      Value returned by the compareTo method if values are not equals
      protected 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)
      For instance,if the Dn is "dc=c, dc=b, dc=a", then the RDNs are stored as : [0] : dc=c [1] : dc=b [2] : dc=a
      static Dn ROOT_DSE
      The rootDSE

    • Constructor Summary

      Constructors 
      Constructor Description
      Dn()
      Construct an empty Dn object
      Dn​(String... upRdns)
      Creates a new instance of Dn, using varargs to declare the RDNs.
      Dn​(Rdn... rdns)
      Creates a Dn from a list of Rdns.
      Dn​(Rdn rdn, Dn dn)
      Creates a Dn concatenating a Rdn and a Dn.
      Dn​(SchemaManager schemaManager)
      Construct an empty Schema aware Dn object
      Dn​(SchemaManager schemaManager, String... upRdns)
      Creates a new instance of schema aware Dn, using varargs to declare the RDNs.
      Dn​(SchemaManager schemaManager, Dn dn)
      Construct an empty Schema aware Dn object
      Dn​(SchemaManager schemaManager, Rdn... rdns)
      Creates a Schema aware Dn from a list of Rdns.

    • Field Detail

      • LOG

        protected static final 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 transient 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)
        For instance,if the Dn is "dc=c, dc=b, dc=a", then the RDNs are stored as :
        • [0] : dc=c
        • [1] : dc=b
        • [2] : dc=a

      • EMPTY_DN

        public static final Dn EMPTY_DN
        A null Dn

      • ROOT_DSE

        public static final Dn ROOT_DSE
        The rootDSE

    • Constructor Detail

      • Dn

        public Dn()
        Construct an empty Dn object

      • Dn

        public Dn​(SchemaManager schemaManager)
        Construct an empty Schema aware Dn object
        Parameters:
        schemaManager - The SchemaManager to use

      • Dn

        public Dn​(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.
        The created Dn is Schema aware.

        An example of usage would be : 
         String exampleName = "example";
 String baseDn = "dc=apache,dc=org";

 Dn dn = new Dn( DefaultSchemaManager.INSTANCE,
     "cn=Test",
     "ou", exampleName,
     baseDn);
        Parameters:
        upRdns - The list of String composing the Dn
        Throws:
        LdapInvalidDnException - If the resulting Dn is invalid

      • Dn

        public Dn​(SchemaManager schemaManager,
          String... upRdns)
   throws LdapInvalidDnException
        Creates a new instance of schema aware 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.
        The created Dn is Schema aware.

        An example of usage would be : 
         String exampleName = "example";
 String baseDn = "dc=apache,dc=org";

 Dn dn = new Dn( DefaultSchemaManager.INSTANCE,
     "cn=Test",
     "ou", exampleName,
     baseDn);
        Parameters:
        schemaManager - the schema manager
        upRdns - The list of String composing the Dn
        Throws:
        LdapInvalidDnException - If the resulting Dn is invalid

      • Dn

        public Dn​(SchemaManager schemaManager,
          Rdn... rdns)
   throws LdapInvalidDnException
        Creates a Schema aware Dn from a list of Rdns.
        Parameters:
        schemaManager - The SchemaManager to use
        rdns - the list of Rdns to be used for the Dn
        Throws:
        LdapInvalidDnException - If the resulting Dn is invalid

    • Method Detail

      • getSchemaManager

        public SchemaManager getSchemaManager()
        Get the associated SchemaManager if any.
        Returns:
        The SchemaManager

      • hashCode

        public int hashCode()
        Gets the hash code of this Dn.
        Overrides:
        hashCode in class Object
        Returns:
        the instance hash code
        See Also:
        Object.hashCode()

      • getName

        public String getName()
        Get the user provided Dn
        Returns:
        The user provided Dn as a String

      • getNormName

        public String getNormName()
        Get the normalized Dn
        Returns:
        The normalized Dn as a String

      • getEscaped

        public String getEscaped()
        Returns:
        The RDN as an escaped String

      • setUpName

        void setUpName​(String upName)
        Sets the up name. Package private because Dn is immutable, only used by the Dn parser.
        Parameters:
        upName - the new up name

      • setNormName

        void setNormName​(String normName)
        Sets the normalized name. Package private because Dn is immutable, only used by the Dn parser.
        Parameters:
        normName - the new normalized name

      • size

        public int size()
        Get the number of RDNs present in the DN
        Returns:
        The umber of RDNs in the DN

      • isAncestorOf

        public boolean isAncestorOf​(String dn)
        Tells if the current Dn is a parent of another Dn.
        For instance, dc=com is a ancestor of dc=example, dc=com
        Parameters:
        dn - The child
        Returns:
        true if the current Dn is a parent of the given Dn

      • isAncestorOf

        public boolean isAncestorOf​(Dn dn)
        Tells if the current Dn is a parent of another Dn.
        For instance, dc=com is a ancestor of dc=example, dc=com
        Parameters:
        dn - The child
        Returns:
        true if the current Dn is a parent of the given Dn

      • isDescendantOf

        public boolean isDescendantOf​(String dn)
        Tells if a Dn is a child of another Dn.
        For instance, dc=example, dc=com is a descendant of dc=com
        Parameters:
        dn - The parent
        Returns:
        true if the current Dn is a child of the given Dn

      • isDescendantOf

        public boolean isDescendantOf​(Dn dn)
        Tells if a Dn is a child of another Dn.
        For instance, dc=example, dc=apache, dc=com is a descendant of dc=com
        Parameters:
        dn - The parent
        Returns:
        true if the current Dn is a child of the given Dn

      • isEmpty

        public boolean isEmpty()
        Tells if the Dn contains no Rdn
        Returns:
        true if the Dn is empty

      • isRootDse

        public boolean isRootDse()
        Tells if the Dn is the RootDSE Dn (ie, an empty Dn)
        Returns:
        true if the Dn is the RootDSE's 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:
        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 List<Rdn> getRdns()
        Retrieves all the components of this name.
        Returns:
        All the components

      • getDescendantOf

        public Dn getDescendantOf​(String ancestor)
                   throws LdapInvalidDnException
        Get the descendant of a given DN, using the ancestr DN. Assuming that a DN has two parts :
        DN = [descendant DN][ancestor DN]
        To get back the descendant from the full DN, you just pass the ancestor DN as a parameter. Here is a working example : 
         Dn dn = new Dn( "cn=test, dc=server, dc=directory, dc=apache, dc=org" );

 Dn descendant = dn.getDescendantOf( "dc=apache, dc=org" );

 // At this point, the descendant contains cn=test, dc=server, dc=directory"
        Parameters:
        ancestor - The parent DN
        Returns:
        The part of the DN that is the descendant
        Throws:
        LdapInvalidDnException - If the Dn is invalid

      • getDescendantOf

        public Dn getDescendantOf​(Dn ancestor)
                   throws LdapInvalidDnException
        Get the descendant of a given DN, using the ancestr DN. Assuming that a DN has two parts :
        DN = [descendant DN][ancestor DN]
        To get back the descendant from the full DN, you just pass the ancestor DN as a parameter. Here is a working example : 
         Dn dn = new Dn( "cn=test, dc=server, dc=directory, dc=apache, dc=org" );

 Dn descendant = dn.getDescendantOf( "dc=apache, dc=org" );

 // At this point, the descendant contains cn=test, dc=server, dc=directory"
        Parameters:
        ancestor - The parent DN
        Returns:
        The part of the DN that is the descendant
        Throws:
        LdapInvalidDnException - If the Dn is invalid

      • getAncestorOf

        public Dn getAncestorOf​(String descendant)
                 throws LdapInvalidDnException
        Get the ancestor of a given DN, using the descendant DN. Assuming that a DN has two parts :
        DN = [descendant DN][ancestor DN]
        To get back the ancestor from the full DN, you just pass the descendant DN as a parameter. Here is a working example : 
         Dn dn = new Dn( "cn=test, dc=server, dc=directory, dc=apache, dc=org" );

 Dn ancestor = dn.getAncestorOf( "cn=test, dc=server, dc=directory" );

 // At this point, the ancestor contains "dc=apache, dc=org"
        Parameters:
        descendant - The child DN
        Returns:
        The part of the DN that is the ancestor
        Throws:
        LdapInvalidDnException - If the Dn is invalid

      • getAncestorOf

        public Dn getAncestorOf​(Dn descendant)
                 throws LdapInvalidDnException
        Get the ancestor of a given DN, using the descendant DN. Assuming that a DN has two parts :
        DN = [descendant DN][ancestor DN]
        To get back the ancestor from the full DN, you just pass the descendant DN as a parameter. Here is a working example : 
         Dn dn = new Dn( "cn=test, dc=server, dc=directory, dc=apache, dc=org" );

 Dn ancestor = dn.getAncestorOf( new Dn( "cn=test, dc=server, dc=directory" ) );

 // At this point, the ancestor contains "dc=apache, dc=org"
        Parameters:
        descendant - The child DN
        Returns:
        The part of the DN that is the ancestor
        Throws:
        LdapInvalidDnException - If the Dn is invalid

      • add

        public Dn add​(Dn rdns)
       throws LdapInvalidDnException
        Adds all RDNs of the provided DN to the (leaf) end of this name. For instance, if the current Dn is "dc=example,dc=com", and the rdns "ou=people", then the resulting Dn will be "ou=people,dc=example,dc=com".
        Parameters:
        rdns - the RDNs to add
        Returns:
        the updated cloned Dn
        Throws:
        LdapInvalidDnException - If the resulting Dn is not valid

      • add

        public Dn add​(String rdn)
       throws LdapInvalidDnException
        Adds a single Rdn to the (leaf) end of this name. For instance, if the current Dn is "dc=example,dc=com", and the rdn "ou=people", then the resulting Dn will be "ou=people,dc=example,dc=com".
        Parameters:
        rdn - the Rdn to add
        Returns:
        the updated cloned Dn
        Throws:
        LdapInvalidDnException - If the resulting Dn is not valid

      • getParent

        public Dn getParent()
        Gets the parent Dn of this Dn. Null if this Dn doesn't have a parent, i.e. because it is the empty Dn.
        The Parent is the right part of the Dn, when the Rdn has been removed.
        Returns:
        the parent Dn of this Dn

      • isSchemaAware

        public boolean isSchemaAware()
        Tells if the Dn is schema aware
        Returns:
        true if the Dn is schema aware.

      • iterator

        public Iterator<Rdn> iterator()
        Iterate over the inner Rdn. The Rdn are returned from the rightmost to the leftmost. For instance, the following code :
         Dn dn = new Dn( "sn=test, dc=apache, dc=org );

 for ( Rdn rdn : dn )
 {
     System.out.println( rdn.toString() );
 }
        will produce this output : 
         dc=org
 dc=apache
 sn=test
        Specified by:
        iterator in interface Iterable<Rdn>

      • isNullOrEmpty

        public static boolean isNullOrEmpty​(Dn dn)
        Check if a DistinguishedName is null or empty.
        Parameters:
        dn - The Dn to check
        Returns:
        true if the Dn is null or empty, false otherwise

      • isValid

        public static boolean isValid​(String name)
        Check if a DistinguishedName is syntactically valid.
        Parameters:
        name - The Dn to validate
        Returns:
        true if the Dn is valid, false otherwise

      • isValid

        public static boolean isValid​(SchemaManager schemaManager,
                              String name)
        Check if a DistinguishedName is syntactically valid.
        Parameters:
        schemaManager - The SchemaManager to use
        name - The Dn to validate
        Returns:
        true if the Dn is valid, false otherwise

      • toString

        public String toString()
        Return the user provided Dn as a String. It returns the same value as the getName method
        Overrides:
        toString in class Object
        Returns:
        A String representing the user provided Dn