Package org.springframework.ldap.core

Class DistinguishedName

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<java.lang.Object>, javax.naming.Name
    public class DistinguishedName
extends java.lang.Object
implements javax.naming.Name
    Deprecated.
    As of 2.0 it is recommended to use LdapName along with utility methods in LdapUtils instead.
    Default implementation of a Name corresponding to an LDAP path. A Distinguished Name manipulation implementation is included in JDK1.5 (LdapName), but not in prior releases. A DistinguishedName is particularly useful when building or modifying an LDAP path dynamically, as escaping will be taken care of. A path is split into several names. The Name interface specifies that the most significant part be in position 0.

    Example:

    The path
    uid=adam.skogman, ou=People, ou=EU
    Name[0]
    ou=EU
    Name[1]
    ou=People
    Name[2]
    uid=adam.skogman

    Name instances, and consequently DistinguishedName instances are naturally mutable, which is useful when constructing DistinguishedNames. Example: 

     DistinguishedName path = new DistinguishedName("dc=jayway,dc=se");
 path.add("ou", "People");
 path.add("uid", "adam.skogman");
 String dn = path.toString();
    will render uid=adam.skogman,ou=People,dc=jayway,dc=se.

    NOTE: The fact that DistinguishedName instances are mutable needs to be taken into careful account, as this means that they may be modified involuntarily. This means that whenever a DistinguishedName instance is kept for reference (e.g. for identification of a domain entry) or as a constant, you should consider getting an immutable copy of the instance using immutableDistinguishedName() or immutableDistinguishedName(String).

    NB:As of version 1.3 the default toString representation of DistinguishedName now defaults to a compact one, without spaces between the respective RDNs. For backward compatibility, set the SPACED_DN_FORMAT_PROPERTY ("org.springframework.ldap.core.spacedDnFormat") to true.

    See Also:
    LdapName, LdapUtils.newLdapName(javax.naming.Name), LdapUtils.newLdapName(String), LdapUtils.emptyLdapName(), Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static DistinguishedName EMPTY_PATH
      Deprecated.
      An empty, unmodifiable DistinguishedName.
      static java.lang.String KEY_CASE_FOLD_LOWER
      Deprecated.
       
      static java.lang.String KEY_CASE_FOLD_NONE
      Deprecated.
       
      static java.lang.String KEY_CASE_FOLD_PROPERTY
      Deprecated.
      System property that will be inspected to determine whether creating a DistinguishedName will convert the keys to lowercase, convert the keys to uppercase, or leave the keys as they were in the original String, ie none.
      static java.lang.String KEY_CASE_FOLD_UPPER
      Deprecated.
       
      static java.lang.String SPACED_DN_FORMAT_PROPERTY
      Deprecated.
      System property that will be inspected to determine whether toString() will format the DN with spaces after each comma or use a more compact representation, i.e.: uid=adam.skogman, ou=People, dc=jayway, dc=se rather than uid=adam.skogman,ou=People,dc=jayway,dc=se.

    • Constructor Summary

      Constructors 
      Constructor Description
      DistinguishedName()
      Deprecated.
      Construct a new DistinguishedName with no components.
      DistinguishedName​(java.lang.String path)
      Deprecated.
      Construct a new DistinguishedName from a String.
      DistinguishedName​(java.util.List list)
      Deprecated.
      Construct a new DistinguishedName from the supplied List of LdapRdn objects.
      DistinguishedName​(javax.naming.Name name)
      Deprecated.
      Construct a new DistinguishedName from the supplied Name.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      javax.naming.Name add​(int index, java.lang.String string)
      Deprecated.
       
      void add​(int idx, LdapRdn rdn)
      Deprecated.
      Add the supplied LdapRdn att the specified index.
      javax.naming.Name add​(java.lang.String string)
      Deprecated.
       
      void add​(java.lang.String key, java.lang.String value)
      Deprecated.
      Add a new LdapRdn using the supplied key and value.
      void add​(LdapRdn rdn)
      Deprecated.
      Add the supplied LdapRdn last in the list of Rdns.
      javax.naming.Name addAll​(int arg0, javax.naming.Name name)
      Deprecated.
       
      javax.naming.Name addAll​(javax.naming.Name name)
      Deprecated.
       
      DistinguishedName append​(java.lang.String key, java.lang.String value)
      Deprecated.
      Append a new LdapRdn using the supplied key and value.
      DistinguishedName append​(DistinguishedName path)
      Deprecated.
      Add an LDAP path last in this DistinguishedName.
      java.lang.Object clone()
      Deprecated.
       
      int compareTo​(java.lang.Object obj)
      Deprecated.
      Compare this instance to another object.
      boolean contains​(DistinguishedName path)
      Deprecated.
      Determines if this DistinguishedName path contains another path.
      java.lang.String encode()
      Deprecated.
      Builds a complete LDAP path, ldap encoded, useful as a DN.
      boolean endsWith​(javax.naming.Name name)
      Deprecated.
      Determines if this DistinguishedName ends with a certian path.
      boolean equals​(java.lang.Object obj)
      Deprecated.
       
      java.lang.String get​(int index)
      Deprecated.
       
      java.util.Enumeration getAll()
      Deprecated.
       
      LdapRdn getLdapRdn​(int index)
      Deprecated.
      Get the LdapRdn at a specified position.
      LdapRdn getLdapRdn​(java.lang.String key)
      Deprecated.
      Get the LdapRdn with the specified key.
      java.util.List getNames()
      Deprecated.
      Get the name List.
      javax.naming.Name getPrefix​(int index)
      Deprecated.
       
      javax.naming.Name getSuffix​(int index)
      Deprecated.
       
      java.lang.String getValue​(java.lang.String key)
      Deprecated.
      Get the value of the LdapRdnComponent with the specified key (Attribute value).
      int hashCode()
      Deprecated.
       
      DistinguishedName immutableDistinguishedName()
      Deprecated.
      Return an immutable copy of this instance.
      static DistinguishedName immutableDistinguishedName​(java.lang.String dnString)
      Deprecated.
      Create an immutable DistinguishedName instance, suitable as a constant.
      boolean isEmpty()
      Deprecated.
       
      protected void parse​(java.lang.String path)
      Deprecated.
      Parse the supplied String and make this instance represent the corresponding distinguished name.
      void prepend​(DistinguishedName path)
      Deprecated.
      Add an LDAP path first in this DistinguishedName.
      java.lang.Object remove​(int arg0)
      Deprecated.
       
      LdapRdn removeFirst()
      Deprecated.
      Remove the first part of this DistinguishedName.
      void removeFirst​(javax.naming.Name path)
      Deprecated.
      Remove the supplied path from the beginning of this DistinguishedName if this instance starts with path.
      LdapRdn removeLast()
      Deprecated.
      Remove the last part of this DistinguishedName.
      int size()
      Deprecated.
       
      boolean startsWith​(javax.naming.Name name)
      Deprecated.
       
      java.lang.String toCompactString()
      Deprecated.
      Get the compact String representation of this DistinguishedName.
      java.lang.String toString()
      Deprecated.
      Get the String representation of this DistinguishedName.
      java.lang.String toUrl()
      Deprecated.
      Builds a complete LDAP path, ldap and url encoded.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • SPACED_DN_FORMAT_PROPERTY

        public static final java.lang.String SPACED_DN_FORMAT_PROPERTY
        Deprecated.
        System property that will be inspected to determine whether toString() will format the DN with spaces after each comma or use a more compact representation, i.e.: uid=adam.skogman, ou=People, dc=jayway, dc=se rather than uid=adam.skogman,ou=People,dc=jayway,dc=se. A value other than null or blank will trigger the spaced format. Default is the compact representation.

        Valid values are:

        • blank or null (property not set)
        • any non-blank value
        Since:
        1.3
        See Also:
        toCompactString(), Constant Field Values

      • KEY_CASE_FOLD_PROPERTY

        public static final java.lang.String KEY_CASE_FOLD_PROPERTY
        Deprecated.
        System property that will be inspected to determine whether creating a DistinguishedName will convert the keys to lowercase, convert the keys to uppercase, or leave the keys as they were in the original String, ie none. Default is to convert the keys to lowercase.

        Valid values are:

        • "lower" or blank or null (property not set)
        • "upper"
        • "none"
        Since:
        1.3.1
        See Also:
        KEY_CASE_FOLD_LOWER, KEY_CASE_FOLD_UPPER, KEY_CASE_FOLD_NONE, Constant Field Values

      • KEY_CASE_FOLD_LOWER

        public static final java.lang.String KEY_CASE_FOLD_LOWER
        Deprecated.
        See Also:
        Constant Field Values

      • KEY_CASE_FOLD_UPPER

        public static final java.lang.String KEY_CASE_FOLD_UPPER
        Deprecated.
        See Also:
        Constant Field Values

      • KEY_CASE_FOLD_NONE

        public static final java.lang.String KEY_CASE_FOLD_NONE
        Deprecated.
        See Also:
        Constant Field Values

      • EMPTY_PATH

        public static final DistinguishedName EMPTY_PATH
        Deprecated.
        An empty, unmodifiable DistinguishedName.

    • Constructor Detail

      • DistinguishedName

        public DistinguishedName()
        Deprecated.
        Construct a new DistinguishedName with no components.

      • DistinguishedName

        public DistinguishedName​(java.lang.String path)
        Deprecated.
        Construct a new DistinguishedName from a String.
        Parameters:
        path - a String corresponding to a (syntactically) valid LDAP path.

      • DistinguishedName

        public DistinguishedName​(java.util.List list)
        Deprecated.
        Construct a new DistinguishedName from the supplied List of LdapRdn objects.
        Parameters:
        list - the components that this instance will consist of.

      • DistinguishedName

        public DistinguishedName​(javax.naming.Name name)
        Deprecated.
        Construct a new DistinguishedName from the supplied Name. The parts of the supplied Name must be syntactically correct LdapRdns.
        Parameters:
        name - the Name to construct a new DistinguishedName from.

    • Method Detail

      • parse

        protected final void parse​(java.lang.String path)
        Deprecated.
        Parse the supplied String and make this instance represent the corresponding distinguished name.
        Parameters:
        path - the LDAP path to parse.

      • getLdapRdn

        public LdapRdn getLdapRdn​(int index)
        Deprecated.
        Get the LdapRdn at a specified position.
        Parameters:
        index - the LdapRdn to retrieve.
        Returns:
        the LdapRdn at the requested position.

      • getLdapRdn

        public LdapRdn getLdapRdn​(java.lang.String key)
        Deprecated.
        Get the LdapRdn with the specified key. If there are several Rdns with the same key, the first one found (in order of significance) will be returned.
        Parameters:
        key - Attribute name of the LdapRdn to retrieve.
        Returns:
        the LdapRdn with the requested key.
        Throws:
        java.lang.IllegalArgumentException - if no Rdn matches the given key.

      • getValue

        public java.lang.String getValue​(java.lang.String key)
        Deprecated.
        Get the value of the LdapRdnComponent with the specified key (Attribute value). If there are several Rdns with the same key, the value of the first one found (in order of significance) will be returned.
        Parameters:
        key - Attribute name of the LdapRdn to retrieve.
        Returns:
        the value.
        Throws:
        java.lang.IllegalArgumentException - if no Rdn matches the given key.

      • getNames

        public java.util.List getNames()
        Deprecated.
        Get the name List.
        Returns:
        the list of LdapRdns that this DistinguishedName consists of.

      • toString

        public java.lang.String toString()
        Deprecated.
        Get the String representation of this DistinguishedName. Depending on the setting of property org.springframework.ldap.core.spacedDnFormat a space will be added after each comma, to make the result more readable. Default is compact representation, i.e. without any spaces.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a syntactically correct, properly escaped String representation of the DistinguishedName.
        See Also:
        SPACED_DN_FORMAT_PROPERTY

      • toCompactString

        public java.lang.String toCompactString()
        Deprecated.
        Get the compact String representation of this DistinguishedName. Add no space after each comma, to make it compact.
        Returns:
        a syntactically correct, properly escaped String representation of the DistinguishedName.

      • encode

        public java.lang.String encode()
        Deprecated.
        Builds a complete LDAP path, ldap encoded, useful as a DN. Always uses lowercase, always separates with ", " i.e. comma and a space.
        Returns:
        the LDAP path.

      • toUrl

        public java.lang.String toUrl()
        Deprecated.
        Builds a complete LDAP path, ldap and url encoded. Separates only with ",".
        Returns:
        the LDAP path, for use in an url.

      • contains

        public boolean contains​(DistinguishedName path)
        Deprecated.
        Determines if this DistinguishedName path contains another path.
        Parameters:
        path - the path to check.
        Returns:
        true if the supplied path is conained in this instance, false otherwise.

      • append

        public DistinguishedName append​(DistinguishedName path)
        Deprecated.
        Add an LDAP path last in this DistinguishedName. E.g.: 
         DistinguishedName name1 = new DistinguishedName("c=SE, dc=jayway, dc=se");
 DistinguishedName name2 = new DistinguishedName("ou=people");
 name1.append(name2);
        will result in ou=people, c=SE, dc=jayway, dc=se
        Parameters:
        path - the path to append.
        Returns:
        this instance.

      • append

        public DistinguishedName append​(java.lang.String key,
                                java.lang.String value)
        Deprecated.
        Append a new LdapRdn using the supplied key and value.
        Parameters:
        key - the key of the LdapRdn.
        value - the value of the LdapRdn.
        Returns:
        this instance.

      • prepend

        public void prepend​(DistinguishedName path)
        Deprecated.
        Add an LDAP path first in this DistinguishedName. E.g.: 
         DistinguishedName name1 = new DistinguishedName("ou=people");
 DistinguishedName name2 = new DistinguishedName("c=SE, dc=jayway, dc=se");
 name1.prepend(name2);
        will result in ou=people, c=SE, dc=jayway, dc=se
        Parameters:
        path - the path to prepend.

      • removeFirst

        public LdapRdn removeFirst()
        Deprecated.
        Remove the first part of this DistinguishedName.
        Returns:
        the removed entry.

      • removeFirst

        public void removeFirst​(javax.naming.Name path)
        Deprecated.
        Remove the supplied path from the beginning of this DistinguishedName if this instance starts with path. Useful for stripping base path suffix from a DistinguishedName.
        Parameters:
        path - the path to remove from the beginning of this instance.

      • clone

        public java.lang.Object clone()
        Deprecated.
        Specified by:
        clone in interface javax.naming.Name
        Overrides:
        clone in class java.lang.Object
        See Also:
        Object.clone()

      • equals

        public boolean equals​(java.lang.Object obj)
        Deprecated.
        Overrides:
        equals in class java.lang.Object
        See Also:
        Object.equals(java.lang.Object)

      • hashCode

        public int hashCode()
        Deprecated.
        Overrides:
        hashCode in class java.lang.Object
        See Also:
        Object.hashCode()

      • compareTo

        public int compareTo​(java.lang.Object obj)
        Deprecated.
        Compare this instance to another object. Note that the comparison is done in order of significance, so the most significant Rdn is compared first, then the second and so on.
        Specified by:
        compareTo in interface java.lang.Comparable<java.lang.Object>
        Specified by:
        compareTo in interface javax.naming.Name
        See Also:
        Name.compareTo(java.lang.Object)

      • size

        public int size()
        Deprecated.
        Specified by:
        size in interface javax.naming.Name

      • isEmpty

        public boolean isEmpty()
        Deprecated.
        Specified by:
        isEmpty in interface javax.naming.Name

      • getAll

        public java.util.Enumeration getAll()
        Deprecated.
        Specified by:
        getAll in interface javax.naming.Name

      • get

        public java.lang.String get​(int index)
        Deprecated.
        Specified by:
        get in interface javax.naming.Name

      • getPrefix

        public javax.naming.Name getPrefix​(int index)
        Deprecated.
        Specified by:
        getPrefix in interface javax.naming.Name

      • getSuffix

        public javax.naming.Name getSuffix​(int index)
        Deprecated.
        Specified by:
        getSuffix in interface javax.naming.Name

      • startsWith

        public boolean startsWith​(javax.naming.Name name)
        Deprecated.
        Specified by:
        startsWith in interface javax.naming.Name

      • endsWith

        public boolean endsWith​(javax.naming.Name name)
        Deprecated.
        Determines if this DistinguishedName ends with a certian path. If the argument path is empty (no names in path) this method will return false.
        Specified by:
        endsWith in interface javax.naming.Name
        Parameters:
        name - The suffix to check for.

      • addAll

        public javax.naming.Name addAll​(javax.naming.Name name)
                         throws javax.naming.InvalidNameException
        Deprecated.
        Specified by:
        addAll in interface javax.naming.Name
        Throws:
        javax.naming.InvalidNameException

      • addAll

        public javax.naming.Name addAll​(int arg0,
                                javax.naming.Name name)
                         throws javax.naming.InvalidNameException
        Deprecated.
        Specified by:
        addAll in interface javax.naming.Name
        Throws:
        javax.naming.InvalidNameException

      • add

        public javax.naming.Name add​(java.lang.String string)
                      throws javax.naming.InvalidNameException
        Deprecated.
        Specified by:
        add in interface javax.naming.Name
        Throws:
        javax.naming.InvalidNameException

      • add

        public javax.naming.Name add​(int index,
                             java.lang.String string)
                      throws javax.naming.InvalidNameException
        Deprecated.
        Specified by:
        add in interface javax.naming.Name
        Throws:
        javax.naming.InvalidNameException

      • remove

        public java.lang.Object remove​(int arg0)
                        throws javax.naming.InvalidNameException
        Deprecated.
        Specified by:
        remove in interface javax.naming.Name
        Throws:
        javax.naming.InvalidNameException

      • removeLast

        public LdapRdn removeLast()
        Deprecated.
        Remove the last part of this DistinguishedName.
        Returns:
        the removed LdapRdn.

      • add

        public void add​(java.lang.String key,
                java.lang.String value)
        Deprecated.
        Add a new LdapRdn using the supplied key and value.
        Parameters:
        key - the key of the LdapRdn.
        value - the value of the LdapRdn.

      • add

        public void add​(LdapRdn rdn)
        Deprecated.
        Add the supplied LdapRdn last in the list of Rdns.
        Parameters:
        rdn - the LdapRdn to add.

      • add

        public void add​(int idx,
                LdapRdn rdn)
        Deprecated.
        Add the supplied LdapRdn att the specified index.
        Parameters:
        idx - the index at which to add the LdapRdn.
        rdn - the LdapRdn to add.

      • immutableDistinguishedName

        public DistinguishedName immutableDistinguishedName()
        Deprecated.
        Return an immutable copy of this instance. It will not be possible to add or remove any Rdns to or from the returned instance, and the respective Rdns will also be immutable in turn.
        Returns:
        a copy of this instance backed by an immutable list.
        Since:
        1.2

      • immutableDistinguishedName

        public static final DistinguishedName immutableDistinguishedName​(java.lang.String dnString)
        Deprecated.
        Create an immutable DistinguishedName instance, suitable as a constant.
        Parameters:
        dnString - the DN string to parse.
        Returns:
        an immutable DistinguishedName corresponding to the supplied DN string.
        Since:
        1.3