Module java.naming
Package javax.naming.ldap

Class LdapName

java.lang.Object
javax.naming.ldap.LdapName
All Implemented Interfaces:
Serializable, Cloneable, Comparable<Object>, Name
public class LdapName extends Object implements Name
This class represents a distinguished name as specified by RFC 2253. A distinguished name, or DN, is composed of an ordered list of components called relative distinguished names, or RDNs. Details of a DN's syntax are described in RFC 2253.

This class resolves a few ambiguities found in RFC 2253 as follows:

  • RFC 2253 leaves the term "whitespace" undefined. The ASCII space character 0x20 (" ") is used in its place.
  • Whitespace is allowed on either side of ',', ';', '=', and '+'. Such whitespace is accepted but not generated by this code, and is ignored when comparing names.
  • AttributeValue strings containing '=' or non-leading '#' characters (unescaped) are accepted.

String names passed to LdapName or returned by it use the full Unicode character set. They may also contain characters encoded into UTF-8 with each octet represented by a three-character substring such as "\\B4". They may not, however, contain characters encoded into UTF-8 with each octet represented by a single character in the string: the meaning would be ambiguous.

LdapName will properly parse all valid names, but does not attempt to detect all possible violations when parsing invalid names. It is "generous" in accepting invalid names. The "validity" of a name is determined ultimately when it is supplied to an LDAP server, which may accept or reject the name based on factors such as its schema information and interoperability considerations.

When names are tested for equality, attribute types, both binary and string values, are case-insensitive. String values with different but equivalent usage of quoting, escaping, or UTF8-hex-encoding are considered equal. The order of components in multi-valued RDNs (such as "ou=Sales+cn=Bob") is not significant.

The components of a LDAP name, that is, RDNs, are numbered. The indexes of a LDAP name with n RDNs range from 0 to n-1. This range may be written as [0,n). The right most RDN is at index 0, and the left most RDN is at index n-1. For example, the distinguished name: "CN=Steve Kille, O=Isode Limited, C=GB" is numbered in the following sequence ranging from 0 to 2: {C=GB, O=Isode Limited, CN=Steve Kille}. An empty LDAP name is represented by an empty RDN list.

Concurrent multithreaded read-only access of an instance of LdapName need not be synchronized.

Unless otherwise noted, the behavior of passing a null argument to a constructor or method in this class will cause a NullPointerException to be thrown.

Since:
1.5
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    LdapName(String name)
    Constructs an LDAP name from the given distinguished name.
    LdapName(List<Rdn> rdns)
    Constructs an LDAP name given its parsed RDN components.

  • Method Summary

    Modifier and Type
    Method
    Description
    Name
    add(int posn, String comp)
    Adds a single component at a specified position within this LDAP name.
    Name
    add(int posn, Rdn comp)
    Adds a single RDN at a specified position within this LDAP name.
    Name
    add(String comp)
    Adds a single component to the end of this LDAP name.
    Name
    add(Rdn comp)
    Adds a single RDN to the end of this LDAP name.
    Name
    addAll(int posn, List<Rdn> suffixRdns)
    Adds the RDNs of a name -- in order -- at a specified position within this name.
    Name
    addAll(int posn, Name suffix)
    Adds the components of a name -- in order -- at a specified position within this name.
    Name
    addAll(List<Rdn> suffixRdns)
    Adds the RDNs of a name -- in order -- to the end of this name.
    Name
    addAll(Name suffix)
    Adds the components of a name -- in order -- to the end of this name.
    Object
    clone()
    Generates a new copy of this name.
    int
    compareTo(Object obj)
    Compares this LdapName with the specified Object for order.
    boolean
    endsWith(List<Rdn> rdns)
    Determines whether the specified RDN sequence forms a suffix of this LDAP name.
    boolean
    endsWith(Name n)
    Determines whether this LDAP name ends with a specified LDAP name suffix.
    boolean
    equals(Object obj)
    Determines whether two LDAP names are equal.
    String
    get(int posn)
    Retrieves a component of this LDAP name as a string.
    Enumeration<String>
    getAll()
    Retrieves the components of this name as an enumeration of strings.
    Name
    getPrefix(int posn)
    Creates a name whose components consist of a prefix of the components of this LDAP name.
    Rdn
    getRdn(int posn)
    Retrieves an RDN of this LDAP name as an Rdn.
    List<Rdn>
    getRdns()
    Retrieves the list of relative distinguished names.
    Name
    getSuffix(int posn)
    Creates a name whose components consist of a suffix of the components in this LDAP name.
    int
    hashCode()
    Computes the hash code of this LDAP name.
    boolean
    isEmpty()
    Determines whether this LDAP name is empty.
    Object
    remove(int posn)
    Removes a component from this LDAP name.
    int
    size()
    Retrieves the number of components in this LDAP name.
    boolean
    startsWith(List<Rdn> rdns)
    Determines whether the specified RDN sequence forms a prefix of this LDAP name.
    boolean
    startsWith(Name n)
    Determines whether this LDAP name starts with a specified LDAP name prefix.
    String
    toString()
    Returns a string representation of this LDAP name in a format defined by RFC 2253 and described in the class description.

    Methods declared in class java.lang.Object

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

  • Constructor Details

    • LdapName

      public LdapName(String name) throws InvalidNameException
      Constructs an LDAP name from the given distinguished name.
      Parameters:
      name - This is a non-null distinguished name formatted according to the rules defined in RFC 2253.
      Throws:
      InvalidNameException - if a syntax violation is detected.
      See Also:

    • LdapName

      public LdapName(List<Rdn> rdns)
      Constructs an LDAP name given its parsed RDN components.

      The indexing of RDNs in the list follows the numbering of RDNs described in the class description.

      Parameters:
      rdns - The non-null list of Rdns forming this LDAP name.

  • Method Details

    • size

      public int size()
      Retrieves the number of components in this LDAP name.
      Specified by:
      size in interface Name
      Returns:
      The non-negative number of components in this LDAP name.

    • isEmpty

      public boolean isEmpty()
      Determines whether this LDAP name is empty. An empty name is one with zero components.
      Specified by:
      isEmpty in interface Name
      Returns:
      true if this LDAP name is empty, false otherwise.

    • getAll

      public Enumeration<String> getAll()
      Retrieves the components of this name as an enumeration of strings. The effect of updates to this name on this enumeration is undefined. If the name has zero components, an empty (non-null) enumeration is returned. The order of the components returned by the enumeration is same as the order in which the components are numbered as described in the class description.
      Specified by:
      getAll in interface Name
      Returns:
      A non-null enumeration of the components of this LDAP name. Each element of the enumeration is of class String.

    • get

      public String get(int posn)
      Retrieves a component of this LDAP name as a string.
      Specified by:
      get in interface Name
      Parameters:
      posn - The 0-based index of the component to retrieve. Must be in the range [0,size()).
      Returns:
      The non-null component at index posn.
      Throws:
      IndexOutOfBoundsException - if posn is outside the specified range.

    • getRdn

      public Rdn getRdn(int posn)
      Retrieves an RDN of this LDAP name as an Rdn.
      Parameters:
      posn - The 0-based index of the RDN to retrieve. Must be in the range [0,size()).
      Returns:
      The non-null RDN at index posn.
      Throws:
      IndexOutOfBoundsException - if posn is outside the specified range.

    • getPrefix

      public Name getPrefix(int posn)
      Creates a name whose components consist of a prefix of the components of this LDAP name. Subsequent changes to this name will not affect the name that is returned and vice versa.
      Specified by:
      getPrefix in interface Name
      Parameters:
      posn - The 0-based index of the component at which to stop. Must be in the range [0,size()].
      Returns:
      An instance of LdapName consisting of the components at indexes in the range [0,posn). If posn is zero, an empty LDAP name is returned.
      Throws:
      IndexOutOfBoundsException - If posn is outside the specified range.

    • getSuffix

      public Name getSuffix(int posn)
      Creates a name whose components consist of a suffix of the components in this LDAP name. Subsequent changes to this name do not affect the name that is returned and vice versa.
      Specified by:
      getSuffix in interface Name
      Parameters:
      posn - The 0-based index of the component at which to start. Must be in the range [0,size()].
      Returns:
      An instance of LdapName consisting of the components at indexes in the range [posn,size()). If posn is equal to size(), an empty LDAP name is returned.
      Throws:
      IndexOutOfBoundsException - If posn is outside the specified range.

    • startsWith

      public boolean startsWith(Name n)
      Determines whether this LDAP name starts with a specified LDAP name prefix. A name n is a prefix if it is equal to getPrefix(n.size())--in other words this LDAP name starts with 'n'. If n is null or not a RFC2253 formatted name as described in the class description, false is returned.
      Specified by:
      startsWith in interface Name
      Parameters:
      n - The LDAP name to check.
      Returns:
      true if n is a prefix of this LDAP name, false otherwise.
      See Also:

    • startsWith

      public boolean startsWith(List<