org.springframework.ldap.core

## Class DistinguishedName

- java.lang.Object
- - org.springframework.ldap.core.DistinguishedName

- All Implemented Interfaces:
    Serializable, Cloneable, Comparable<Object>, Name

  Deprecated.
  As of 2.0 it is recommended to use `LdapName` along with utility methods in `LdapUtils` instead.

      public class DistinguishedName
      extends Object
      implements Name

  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`.

  Author:
    Adam Skogman, Mattias Hellborg Arthursson
  See Also:
    `LdapName`, `LdapUtils.newLdapName(javax.naming.Name)`, `LdapUtils.newLdapName(String)`, `LdapUtils.emptyLdapName()`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static DistinguishedName` | `EMPTY_PATH` Deprecated. An empty, unmodifiable DistinguishedName.
    `static String` | `KEY_CASE_FOLD_LOWER` Deprecated.
    `static String` | `KEY_CASE_FOLD_NONE` Deprecated.
    `static 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 String` | `KEY_CASE_FOLD_UPPER` Deprecated.
    `static 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 and Description
    `DistinguishedName()` Deprecated. Construct a new DistinguishedName with no components.
    `DistinguishedName(List list)` Deprecated. Construct a new `DistinguishedName` from the supplied `List` of `LdapRdn` objects.
    `DistinguishedName(Name name)` Deprecated. Construct a new `DistinguishedName` from the supplied `Name`.
    `DistinguishedName(String path)` Deprecated. Construct a new `DistinguishedName` from a String.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(int idx, LdapRdn rdn)` Deprecated. Add the supplied `LdapRdn` att the specified index.
    `Name` | `add(int index, String string)` Deprecated.
    `void` | `add(LdapRdn rdn)` Deprecated. Add the supplied `LdapRdn` last in the list of Rdns.
    `Name` | `add(String string)` Deprecated.
    `void` | `add(String key, String value)` Deprecated. Add a new `LdapRdn` using the supplied key and value.
    `Name` | `addAll(int arg0, Name name)` Deprecated.
    `Name` | `addAll(Name name)` Deprecated.
    `DistinguishedName` | `append(DistinguishedName path)` Deprecated. Add an LDAP path last in this DistinguishedName.
    `DistinguishedName` | `append(String key, String value)` Deprecated. Append a new `LdapRdn` using the supplied key and value.
    `Object` | `clone()` Deprecated.
    `int` | `compareTo(Object obj)` Deprecated. Compare this instance to another object.
    `boolean` | `contains(DistinguishedName path)` Deprecated. Determines if this `DistinguishedName` path contains another path.
    `String` | `encode()` Deprecated. Builds a complete LDAP path, ldap encoded, useful as a DN.
    `boolean` | `endsWith(Name name)` Deprecated. Determines if this `DistinguishedName` ends with a certian path.
    `boolean` | `equals(Object obj)` Deprecated.
    `String` | `get(int index)` Deprecated.
    `Enumeration` | `getAll()` Deprecated.
    `LdapRdn` | `getLdapRdn(int index)` Deprecated. Get the `LdapRdn` at a specified position.
    `LdapRdn` | `getLdapRdn(String key)` Deprecated. Get the `LdapRdn` with the specified key.
    `List` | `getNames()` Deprecated. Get the name `List`.
    `Name` | `getPrefix(int index)` Deprecated.
    `Name` | `getSuffix(int index)` Deprecated.
    `String` | `getValue(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(String dnString)` Deprecated. Create an immutable DistinguishedName instance, suitable as a constant.
    `boolean` | `isEmpty()` Deprecated.
    `protected void` | `parse(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.
    `Object` | `remove(int arg0)` Deprecated.
    `LdapRdn` | `removeFirst()` Deprecated. Remove the first part of this `DistinguishedName`.
    `void` | `removeFirst(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(Name name)` Deprecated.
    `String` | `toCompactString()` Deprecated. Get the compact String representation of this `DistinguishedName`.
    `String` | `toString()` Deprecated. Get the String representation of this `DistinguishedName`.
    `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 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 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 String KEY_CASE_FOLD_LOWER

      Deprecated.
      See Also:
        Constant Field Values

    - #### KEY_CASE_FOLD_UPPER

          public static final String KEY_CASE_FOLD_UPPER

      Deprecated.
      See Also:
        Constant Field Values

    - #### KEY_CASE_FOLD_NONE

          public static final 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(String path)

      Deprecated.
      Construct a new `DistinguishedName` from a String.
      Parameters:
        `path` - a String corresponding to a (syntactically) valid LDAP path.

    - #### DistinguishedName

          public DistinguishedName(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(Name name)

      Deprecated.
      Construct a new `DistinguishedName` from the supplied `Name`. The parts of the supplied `Name` must be syntactically correct `LdapRdn`s.
      Parameters:
        `name` - the `Name` to construct a new `DistinguishedName` from.

  - ### Method Detail

    - #### parse

          protected final void parse(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(String key)

      Deprecated.
      Get the `LdapRdn` with the specified key. If there are several `Rdn`s 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:
        `IllegalArgumentException` - if no Rdn matches the given key.

    - #### getValue

          public String getValue(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:
        `IllegalArgumentException` - if no Rdn matches the given key.

    - #### getNames

          public List getNames()

      Deprecated.
      Get the name `List`.
      Returns:
        the list of `LdapRdn`s that this `DistinguishedName` consists of.

    - #### toString

          public 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 `Object`
      Returns:
        a syntactically correct, properly escaped String representation of the `DistinguishedName`.
      See Also:
        `SPACED_DN_FORMAT_PROPERTY`

    - #### toCompactString

          public 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 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 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(String key,
                                          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(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 Object clone()

      Deprecated.
      Specified by:
        `clone` in interface `Name`
      Overrides:
        `clone` in class `Object`
      See Also:
        `Object.clone()`

    - #### equals

          public boolean equals(Object obj)

      Deprecated.
      Overrides:
        `equals` in class `Object`
      See Also:
        `Object.equals(java.lang.Object)`

    - #### hashCode

          public int hashCode()

      Deprecated.
      Overrides:
        `hashCode` in class `Object`
      See Also:
        `Object.hashCode()`

    - #### compareTo

          public int compareTo(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 `Comparable<Object>`
      Specified by:
        `compareTo` in interface `Name`
      See Also:
        `Name.compareTo(java.lang.Object)`

    - #### size

          public int size()

      Deprecated.
      Specified by:
        `size` in interface `Name`

    - #### isEmpty

          public boolean isEmpty()

      Deprecated.
      Specified by:
        `isEmpty` in interface `Name`

    - #### getAll

          public Enumeration getAll()

      Deprecated.
      Specified by:
        `getAll` in interface `Name`

    - #### get

          public String get(int index)

      Deprecated.
      Specified by:
        `get` in interface `Name`

    - #### getPrefix

          public Name getPrefix(int index)

      Deprecated.
      Specified by:
        `getPrefix` in interface `Name`

    - #### getSuffix

          public Name getSuffix(int index)

      Deprecated.
      Specified by:
        `getSuffix` in interface `Name`

    - #### startsWith

          public boolean startsWith(Name name)

      Deprecated.
      Specified by:
        `startsWith` in interface `Name`

    - #### endsWith

          public boolean endsWith(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 `Name`
      Parameters:
        `name` - The suffix to check for.

    - #### addAll

          public Name addAll(Name name)
                      throws InvalidNameException

      Deprecated.
      Specified by:
        `addAll` in interface `Name`
      Throws:
        `InvalidNameException`

    - #### addAll

          public Name addAll(int arg0,
                             Name name)
                      throws InvalidNameException

      Deprecated.
      Specified by:
        `addAll` in interface `Name`
      Throws:
        `InvalidNameException`

    - #### add

          public Name add(String string)
                   throws InvalidNameException

      Deprecated.
      Specified by:
        `add` in interface `Name`
      Throws:
        `InvalidNameException`

    - #### add

          public Name add(int index,
                          String string)
                   throws InvalidNameException

      Deprecated.
      Specified by:
        `add` in interface `Name`
      Throws:
        `InvalidNameException`

    - #### remove

          public Object remove(int arg0)
                        throws InvalidNameException

      Deprecated.
      Specified by:
        `remove` in interface `Name`
      Throws:
        `InvalidNameException`

    - #### removeLast

          public LdapRdn removeLast()

      Deprecated.
      Remove the last part of this `DistinguishedName`.
      Returns:
        the removed `LdapRdn`.

    - #### add

          public void add(String key,
                          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(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