DistinguishedName (spring-ldap-core 2.0.3.RELEASE API)

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

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 LdapRdns.
    
    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 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:
    
    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 LdapRdns 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

Class DistinguishedName

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SPACED_DN_FORMAT_PROPERTY

KEY_CASE_FOLD_PROPERTY

KEY_CASE_FOLD_LOWER

KEY_CASE_FOLD_UPPER

KEY_CASE_FOLD_NONE

EMPTY_PATH

Constructor Detail

DistinguishedName

DistinguishedName

DistinguishedName

DistinguishedName

Method Detail

parse

getLdapRdn

getLdapRdn

getValue

getNames

toString

toCompactString

encode

toUrl

contains

append

append

prepend

removeFirst

removeFirst

clone

equals

hashCode

compareTo

size

isEmpty

getAll

get

getPrefix

getSuffix

startsWith

endsWith

addAll

addAll

add

add

remove

removeLast

add

add

add

immutableDistinguishedName

immutableDistinguishedName