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

Class Rdn

  • All Implemented Interfaces:
    Externalizable, Serializable, Cloneable, Comparable<Rdn>, Iterable<Ava>
    public class Rdn
extends Object
implements Cloneable, Externalizable, Iterable<Ava>, Comparable<Rdn>
    This class store the name-component part or the following BNF grammar (as of RFC2253, par. 3, and RFC1779, fig. 1) :
    - <name-component> ::= <attributeType> <spaces> '=' <spaces> <attributeValue> <attributeTypeAndValues>
    - <attributeTypeAndValues> ::= <spaces> '+' <spaces> <attributeType> <spaces> '=' <spaces> <attributeValue> <attributeTypeAndValues> | e
    - <attributeType> ::= [a-zA-Z] <keychars> | <oidPrefix> [0-9] <digits> <oids> | [0-9] <digits> <oids>
    - <keychars> ::= [a-zA-Z] <keychars> | [0-9] <keychars> | '-' <keychars> | e
    - <oidPrefix> ::= 'OID.' | 'oid.' | e
    - <oids> ::= '.' [0-9] <digits> <oids> | e
    - <attributeValue> ::= <pairs-or-strings> | '#' <hexstring> |'"' <quotechar-or-pairs> '"'
    - <pairs-or-strings> ::= '\' <pairchar> <pairs-or-strings> | <stringchar> <pairs-or-strings> | e
    - <quotechar-or-pairs> ::= <quotechar> <quotechar-or-pairs> | '\' <pairchar> <quotechar-or-pairs> | e
    - <pairchar> ::= ',' | '=' | '+' | '<' | '>' | '#' | ';' | '\' | '"' | [0-9a-fA-F] [0-9a-fA-F]
    - <hexstring> ::= [0-9a-fA-F] [0-9a-fA-F] <hexpairs>
    - <hexpairs> ::= [0-9a-fA-F] [0-9a-fA-F] <hexpairs> | e
    - <digits> ::= [0-9] <digits> | e
    - <stringchar> ::= [0x00-0xFF] - [,=+<>#;\"\n\r]
    - <quotechar> ::= [0x00-0xFF] - [\"]
    - <separator> ::= ',' | ';'
    - <spaces> ::= ' ' <spaces> | e

    A Rdn is a part of a Dn. It can be composed of many types, as in the Rdn following Rdn :
    ou=value + cn=other value

    or
    ou=value + ou=another value

    In this case, we have to store an 'ou' and a 'cn' in the Rdn.

    The types are case insensitive.
    Spaces before and after types and values are not stored.
    Spaces before and after '+' are not stored.

    Thus, we can consider that the following RDNs are equals :

    'ou=test 1'
    ' ou=test 1'
    'ou =test 1'
    'ou= test 1'
    'ou=test 1 '
    ' ou = test 1 '

    So are the following :

    'ou=test 1+cn=test 2'
    'ou = test 1 + cn = test 2'
    ' ou =test 1+ cn =test 2 '
    'cn = test 2 +ou = test 1'

    but the following are not equal :
    'ou=test 1'
    'ou=test 1'
    because we have more than one spaces inside the value.

    The Rdn is composed of one or more Ava. Those Avas are ordered in the alphabetical natural order : a < b < c ... < z As the type are not case sensitive, we can say that a = A
    This class is immutable.
    Author:
    Apache Directory Project
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected Ava ava
      A simple Ava is used to store the Rdn for the simple case where we only have a single type=value.
      static Rdn EMPTY_RDN
      An empty Rdn
      static int EQUAL
      Constant used in comparisons
      static int INFERIOR
      Constant used in comparisons
      protected static Logger LOG
      The LoggerFactory used by this class
      static int SUPERIOR
      Constant used in comparisons
      static int UNDEFINED
      CompareTo() results

    • Constructor Summary

      Constructors 
      Constructor Description
      Rdn()
      A empty constructor.
      Rdn​(String rdn)
      A constructor that parse a String representing a Rdn.
      Rdn​(String upType, String upValue)
      A constructor that constructs a Rdn from a type and a value.
      Rdn​(Ava... avas)
      Creates a new RDN from a list of AVA
      Rdn​(Rdn rdn)
      Constructs an Rdn from the given rdn.
      Rdn​(SchemaManager schemaManager)
      Creates a new schema aware instance of Rdn.
      Rdn​(SchemaManager schemaManager, String rdn)
      A constructor that parse a String representing a schema aware Rdn.
      Rdn​(SchemaManager schemaManager, String upType, String upValue)
      A constructor that constructs a schema aware Rdn from a type and a value.
      Rdn​(SchemaManager schemaManager, Ava... avas)
      Creates a new schema aware RDN from a list of AVA
      Rdn​(SchemaManager schemaManager, Rdn rdn)
      Constructs an Rdn from the given rdn.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) void addAVA​(SchemaManager schemaManager, Ava addedAva)
      Add an Ava to the current schema aware Rdn
      (package private) void clear()
      Clear the Rdn, removing all the Avas.
      Rdn clone()
      Clone the Rdn
      int compareTo​(Rdn otherRdn)
      Compare the current RDN with the provided one.
      int deserialize​(byte[] buffer, int pos)
      Deserialize a RDN from a byte[], starting at a given position
      boolean equals​(Object that)
      Compares the specified Object with this Rdn for equality.
      static String escapeValue​(byte[] attrValue)
      Transform a value in a String, accordingly to RFC 2253
      static String escapeValue​(String value)
      Transform a value in a String, accordingly to RFC 2253
      Ava getAva()
      Return the unique Ava, or the first one of we have more than one
      Ava getAva​(int pos)
      Return the Nth Ava
      Ava getAva​(String type)
      Get the Ava which type is given as an argument.
      String getEscaped()  
      String getName()  
      String getNormName()  
      String getNormType()
      Return the normalized type, or the first one of we have more than one (the lowest)
      String getType()
      Return the user provided type, or the first one of we have more than one (the lowest)
      String getValue()
      Return the User Provided value, as a String
      Object getValue​(String type)
      Get the value of the Ava which type is given as an argument.
      int hashCode()
      Gets the hashcode of this rdn.
      boolean isSchemaAware()
      Tells if the Rdn is schema aware.
      static boolean isValid​(String dn)
      Validate a NameComponent :
      static boolean isValid​(SchemaManager schemaManager, String dn)
      Validate a NameComponent :
      Iterator<Ava> iterator()
      Retrieves the components of this Rdn as an iterator of Avas.
      void readExternal​(ObjectInput in)
      We read back the data to create a new RDB.
      int serialize​(byte[] buffer, int pos)
      Serialize a RDN into a byte[]
      (package private) void setNormName​(String normName)
      Set the normalized Name.
      (package private) void setUpName​(String upName)
      Set the User Provided Name.
      int size()
      Get the number of Avas of this Rdn
      String toString()  
      static Object unescapeValue​(String value)
      Unescape the given string according to RFC 2253 If in <string> form, a LDAP string representation asserted value can be obtained by replacing (left-to-right, non-recursively) each <pair> appearing in the <string> as follows: replace <ESC><ESC> with <ESC> replace <ESC><special> with <special> replace <ESC><hexpair> with the octet indicated by the <hexpair> If in <hexstring> form, a BER representation can be obtained from converting each <hexpair> of the <hexstring> to the octet indicated by the <hexpair>
      void writeExternal​(ObjectOutput out)
      A Rdn is composed of on to many Avas (AttributeType And Value).

    • Field Detail

      • LOG

        protected static final Logger LOG
        The LoggerFactory used by this class

      • EMPTY_RDN

        public static final Rdn EMPTY_RDN
        An empty Rdn

      • ava

        protected Ava ava
        A simple Ava is used to store the Rdn for the simple case where we only have a single type=value. This will be 99.99% the case. This avoids the creation of a HashMap.

      • SUPERIOR

        public static final int SUPERIOR
        Constant used in comparisons
        See Also:
        Constant Field Values

      • INFERIOR

        public static final int INFERIOR
        Constant used in comparisons
        See Also:
        Constant Field Values

    • Method Detail

      • clear

        void clear()
        Clear the Rdn, removing all the Avas.

      • getValue

        public Object getValue​(String type)
                throws LdapInvalidDnException
        Get the value of the Ava which type is given as an argument.
        Parameters:
        type - the type of the NameArgument
        Returns:
        the value to be returned, or null if none found.
        Throws:
        LdapInvalidDnException - if the Rdn is invalid

      • getAva

        public Ava getAva​(String type)
        Get the Ava which type is given as an argument. If we have more than one value associated with the type, we will return only the first one.
        Parameters:
        type - The type of the NameArgument to be returned
        Returns:
        The Ava, of null if none is found.

      • iterator

        public Iterator<Ava> iterator()
        Retrieves the components of this Rdn as an iterator of Avas. The effect on the iterator of updates to this Rdn is undefined. If the Rdn has zero components, an empty (non-null) iterator is returned.
        Specified by:
        iterator in interface Iterable<Ava>
        Returns:
        an iterator of the components of this Rdn, each an Ava

      • clone

        public Rdn clone()
        Clone the Rdn
        Overrides:
        clone in class Object
        Returns:
        A clone of the current Rdn

      • getName

        public String getName()
        Returns:
        the user provided name

      • setUpName

        void setUpName​(String upName)
        Set the User Provided Name. Package private because Rdn is immutable, only used by the Dn parser.
        Parameters:
        upName - the User Provided dame

      • getNormName

        public String getNormName()
        Returns:
        the normalized name

      • setNormName

        void setNormName​(String normName)
        Set the normalized Name. Package private because Rdn is immutable, only used by the Dn parser.
        Parameters:
        normName - the Normalized dame

      • getAva

        public Ava getAva()
        Return the unique Ava, or the first one of we have more than one
        Returns:
        The first Ava of this Rdn

      • getAva

        public Ava getAva​(int pos)
        Return the Nth Ava
        Parameters:
        pos - The Ava we are looking for
        Returns:
        The Ava at the given position in this Rdn

      • getType

        public String getType()
        Return the user provided type, or the first one of we have more than one (the lowest)
        Returns:
        The first user provided type of this Rdn

      • getNormType

        public String getNormType()
        Return the normalized type, or the first one of we have more than one (the lowest)
        Returns:
        The first normalized type of this Rdn

      • getValue

        public String getValue()
        Return the User Provided value, as a String
        Returns:
        The first User provided value of this Rdn

      • equals

        public boolean equals​(Object that)
        Compares the specified Object with this Rdn for equality. Returns true if the given object is also a Rdn and the two Rdns represent the same attribute type and value mappings. The order of components in multi-valued Rdns is not significant.
        Overrides:
        equals in class Object
        Parameters:
        that - Rdn to be compared for equality with this Rdn
        Returns:
        true if the specified object is equal to this Rdn

      • size

        public int size()
        Get the number of Avas of this Rdn
        Returns:
        The number of Avas in this Rdn

      • unescapeValue

        public static Object unescapeValue​(String value)
        Unescape the given string according to RFC 2253 If in <string> form, a LDAP string representation asserted value can be obtained by replacing (left-to-right, non-recursively) each <pair> appearing in the <string> as follows:
        • replace <ESC><ESC> with <ESC>
        • replace <ESC><special> with <special>
        • replace <ESC><hexpair> with the octet indicated by the <hexpair>
        If in <hexstring> form, a BER representation can be obtained from converting each <hexpair> of the <hexstring> to the octet indicated by the <hexpair>
        Parameters:
        value - The value to be unescaped
        Returns:
        Returns a string value as a String, and a binary value as a byte array.
        Throws:
        IllegalArgumentException - When an Illegal value is provided.

      • escapeValue

        public static String escapeValue​(String value)
        Transform a value in a String, accordingly to RFC 2253
        Parameters:
        value - The attribute value to be escaped
        Returns:
        The escaped string value.

      • getEscaped

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

      • escapeValue

        public static String escapeValue​(byte[] attrValue)
        Transform a value in a String, accordingly to RFC 2253
        Parameters:
        attrValue - The attribute value to be escaped
        Returns:
        The escaped string value.

      • isSchemaAware

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

      • isValid

        public static boolean isValid​(String dn)
        Validate a NameComponent :

        <name-component> ::= <attributeType> <spaces> '=' <spaces> <attributeValue> <nameComponents>

        Parameters:
        dn - The string to parse
        Returns:
        true if the Rdn is valid

      • isValid

        public static boolean isValid​(SchemaManager schemaManager,
                              String dn)
        Validate a NameComponent :

        <name-component> ::= <attributeType> <spaces> '=' <spaces> <attributeValue> <nameComponents>

        Parameters:
        schemaManager - The Schemamanager to use
        dn - The string to parse
        Returns:
        true if the Rdn is valid

      • hashCode

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

      • serialize

        public int serialize​(byte[] buffer,
                     int pos)
              throws IOException
        Serialize a RDN into a byte[]
        Parameters:
        buffer - The buffer which will contain the serilaized form of this RDN
        pos - The position in the buffer where to store the RDN
        Returns:
        The new position in the byte[]
        Throws:
        IOException - If the serialization failed

      • writeExternal

        public void writeExternal​(ObjectOutput out)
                   throws IOException
        A Rdn is composed of on to many Avas (AttributeType And Value). We should write all those Avas sequencially, following the structure :
        • parentId The parent entry's Id
        • nbAvas The number of Avas to write. Can't be 0.
        • upName The User provided Rdn
        • Avas

        For each Ava :
        • start The position of this Ava in the upName string
        • length The Ava user provided length
        • Call the Ava write method The Ava itself
        Specified by:
        writeExternal in interface Externalizable
        Parameters:
        out - The stream into which the serialized Rdn will be put
        Throws:
        IOException - If the stream can't be written
        See Also:
        Externalizable.readExternal(ObjectInput)

      • compareTo

        public int compareTo​(Rdn otherRdn)
        Compare the current RDN with the provided one.
        Specified by:
        compareTo in interface Comparable<Rdn>
        Parameters:
        otherRdn - The RDN we want to compare to
        Returns:
        a negative value if the current RDN is below the provided one, a positive value if it's above and 0 if they are equal.

      • toString

        public String toString()
        Overrides:
        toString in class Object
        Returns:
        a String representation of the Rdn. The caller will get back the user provided Rdn