Package com.isode.dsapi

Class DN

java.lang.Object
com.isode.dsapi.DN
All Implemented Interfaces:
Serializable, Comparable<DN>, Iterable<RDN>
public class DN extends Object implements Comparable<DN>, Iterable<RDN>, Serializable
Class representing a Distinguished Name.
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    DN()
    Construct a DN that has no RDNs.
    DN(RDN... rdnArray)
    Construct a DN from an array of RDNs.
    DN(String dnStr)
    Constructor from LDAP formatted string DN.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    compareTo(DN other)
    Compare two DNs.
    boolean
    equals(Object anObject)
    Compare this DN to the specified object, and return true iff the argument is a DN that represents the same value as this object.
    protected void
    finalize()
    Releases any native structures associated with this object.
    DN
    getAncestorDN(int generation)
    Find the ancestor DN of this DN
    String
    getCanonicalString()
    Obtain a canonical String representation of this DN.
    DN
    getChildDN(RDN rdn)
    Return a new DN object which is the child of this DN.
    DN
    getNearestCommonAncestor(DN dn)
    Finds the nearest common ancestor DN between this DN and another one.
    DN
    getParentDN()
    Find the parent DN of this DN.
    RDN
    getRDN()
    Return the least significant RDN.
    RDN
    getRDN(int pos)
    Return the RDN at the given position (0 is least significant).
    int
    getRDNCount()
    Get the RDN count.
    DN
    getRelocatedDN(DN source, DN target)
    Find the DN that results from relocating this DN from one subtree to another.
    int
    hashCode()
    Return a hash code value for this DN.
    boolean
    isChildOf(DN dn)
    Check if this DN is an immediate child of the argument.
    boolean
    isDescendantOf(DN dn)
    Check if this DN is a descendant (inferior) of the argument.
    boolean
    isEqualOrDescendantOf(DN dn)
    Check if this DN is equal to or is a descendant of the argument.
    boolean
    isRootDN()
    Determines whether this object represents a root DN
    boolean
    isSameValue(DN value)
    Test whether this distinguished name is equivalent to another.
    Iterator<RDN>
    iterator()
    Returns an iterator over the RDNs in this DN
    protected void
    jni_dispose()
    Native function used to clean up any C data structures attached to this object when it is destroyed in finalization.
    String
    toOIDString()
    Generate a String representation of the DN, including dotted OID values instead of attribute names.
    final String
    toString()
    Return a String representation of the DN, containing attribute names and values.
    final String
    toUIString()
    Return a friendly string representation of the DN (that is, one that contains no attribute type names).

    Methods inherited from class java.lang.Object

    clone, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Constructor Details

    • DN

      public DN()
      Construct a DN that has no RDNs. This is equivalent to using new DN(""), except that because it can't throw a BadDNException, a call to this constructor does not have to be enclosed in a try..catch
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • DN

      public DN(String dnStr) throws BadDNException, NativeLibraryException, NullPointerException
      Constructor from LDAP formatted string DN.
      Parameters:
      dnStr - String representation of DN (must not be NULL).
      Throws:
      BadDNException - if dnStr does not represent a valid DN.
      NativeLibraryException - if an unrecoverable error was detected by the native library
      NullPointerException - if dnStr is null

    • DN

      public DN(RDN... rdnArray)
      Construct a DN from an array of RDNs.
      Parameters:
      rdnArray - Array of RDNs, least significant RDN first. Must not be null.
      Since:
      14.4

  • Method Details

    • jni_dispose

      protected void jni_dispose() throws NativeLibraryException
      Native function used to clean up any C data structures attached to this object when it is destroyed in finalization.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • finalize

      protected void finalize() throws Throwable
      Releases any native structures associated with this object.
      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • getChildDN

      public DN getChildDN(RDN rdn) throws NativeLibraryException
      Return a new DN object which is the child of this DN. For example, the result of: 
          DN parent = new DN("o=Test,c=GB");
    DN child = parent.getChildDN(new RDN("cn=Mr Magoo"));
      would be a new DN containing "cn=Mr Magoo, o=Test, c=GB"
      Parameters:
      rdn - the RDN to add to produce a new DN. Must not be null.
      Returns:
      a new DN object consisting of this DN with rdn added.
      Throws:
      NullPointerException - if rdn is null
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • isSameValue

      public boolean isSameValue(DN value) throws NullPointerException, NativeLibraryException
      Test whether this distinguished name is equivalent to another. This is the same test that equals() does.
      Parameters:
      value - Value to compare against. This may not be null.
      Returns:
      true if the given object represents the same value as this one, false otherwise.
      Throws:
      NullPointerException - if value is null.
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • getParentDN

      public DN getParentDN() throws NativeLibraryException
      Find the parent DN of this DN.
      Returns:
      the parent DN, or null if the DN has no parent (in other words, it represents the root dn)
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • getAncestorDN

      public DN getAncestorDN(int generation) throws NativeLibraryException
      Find the ancestor DN of this DN
      Parameters:
      generation - How far back to go; 0 means this DN; 1 is the direct parent; 2 is the parent's parent, and so on
      Returns:
      a new DN object representing the specified ancestor, or null if generation is larger than the number of ancestors that this DN has.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library.

    • getRelocatedDN

      public DN getRelocatedDN(DN source, DN target) throws NativeLibraryException
      Find the DN that results from relocating this DN from one subtree to another. The relative location of the current DN compared to 'source' is found, which gives a chain of zero or more RDNs which are applied to 'target' to give the result. Null is returned if this DN is outside the 'source' subtree.
      Parameters:
      source - DN of base of source subtree (not null)
      target - DN of base of target subtree (not null)
      Returns:
      A new DN object representing the relocated entry, or null if the DN is not a descendent of source, nor the same as it.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library.

    • isEqualOrDescendantOf

      public boolean isEqualOrDescendantOf(DN dn)
      Check if this DN is equal to or is a descendant of the argument.
      Parameters:
      dn - Compared DN.
      Returns:
      Returns true if this is equal to or a descendant of the argument, false otherwise.
      Since:
      14.4

    • isDescendantOf

      public boolean isDescendantOf(DN dn)
      Check if this DN is a descendant (inferior) of the argument.
      Parameters:
      dn - Compared DN.
      Returns:
      Returns true if this is a descendant of the argument, false otherwise.

    • isChildOf

      public boolean isChildOf(DN dn)
      Check if this DN is an immediate child of the argument.
      Parameters:
      dn - Compared DN.
      Returns:
      Returns true if this is an immediate child of the argument, false otherwise.
      Since:
      14.6

    • isRootDN

      public boolean isRootDN()
      Determines whether this object represents a root DN
      Returns:
      true if this object represents the root DN, false otherwise

    • getRDNCount

      public int getRDNCount()
      Get the RDN count.
      Returns:
      Count of RDNs.

    • getRDN

      public RDN getRDN(int pos)
      Return the RDN at the given position (0 is least significant).
      Parameters:
      pos - Position of RDN in sequence.
      Returns:
      RDN at given position.
      Throws:
      ArrayIndexOutOfBoundsException - if pos out of range.

    • getRDN

      public RDN getRDN()
      Return the least significant RDN. For example, the least significant RDN of "cn=jim, o=isode, c=gb" is "cn=jim".
      Returns:
      least significant RDN
      Throws:
      ArrayIndexOutOfBoundsException - if this object represents the root DN.

    • getNearestCommonAncestor

      public DN getNearestCommonAncestor(DN dn)
      Finds the nearest common ancestor DN between this DN and another one. At one extreme, this will be the root DN if there are no common parents. At the other extreme, the result will be 'this' or 'dn' if one DN is an ancestor of the other.
      Parameters:
      dn - Other DN
      Returns:
      Nearest common ancestor
      Since:
      15.0

    • toUIString

      public final String toUIString()
      Return a friendly string representation of the DN (that is, one that contains no attribute type names). Thus a DN of "cn=Mister Magoo, o=Isode, c=GB" gives "Mister Magoo, Isode, GB".

      Multiple values are separated by non-delimited plus signs, for example "sales+J. Smith". Unlike the toString() method, no escaping of special characters within the values takes place; so an DN representing the common name "nick + tim" will be returned as "nick + tim".

      Returns:
      "UI-friendly" string representation of DN.
      See Also:

    • toString

      public final String toString() throws NativeLibraryException
      Return a String representation of the DN, containing attribute names and values. Multiple values are separated by non-delimited plus signs, for example "ou=sales+cn=J. Smith,c=us". Any special characters within the attribute values will be escaped with a "\". For example a DN representing a common name of "nick + tim" will be returned as "cn=nick \+ tim". The String returned is suitable for using in the DN(String) constructor.
      Overrides:
      toString in class Object
      Returns:
      String representation of DN.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library
      See Also:

    • equals

      public boolean equals(Object anObject) throws NativeLibraryException
      Compare this DN to the specified object, and return true iff the argument is a DN that represents the same value as this object.
      Overrides:
      equals in class Object
      Parameters:
      anObject - an object to compare this DN against.
      Returns:
      true if the values are equal, false otherwise.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library

    • compareTo

      public int compareTo(DN other)
      Compare two DNs. Suitable to sort DNs into a hierarchical order, parents before children, sorted by RDN at each level.
      Specified by:
      compareTo in interface Comparable<DN>
      Parameters:
      other - another DN
      Returns:
      -1, 0 or 1, depending on whether this DN is "less-than", "equal-to" or "greater-than" the DN specified in other

    • hashCode

      public int hashCode()
      Return a hash code value for this DN. The value returned for any two DN object representing the same DN will be identical, even though their String representation may differ.

      This method derives its hash code from the canonical string representation of the DN. Callers may obtain canonical string values using getCanonicalString()

      Overrides:
      hashCode in class Object
      Returns:
      a hash code value for the DN.
      See Also:

    • iterator

      public Iterator<RDN> iterator()
      Returns an iterator over the RDNs in this DN
      Specified by:
      iterator in interface Iterable<RDN>
      Returns:
      an iterator that can be used to process all the RDNs in this DN

    • toOIDString

      public String toOIDString()
      Generate a String representation of the DN, including dotted OID values instead of attribute names.

      String values returned by this method may be used when constructing new DNs, in which case they are considered equivalent to their "non OID" forms. For example 

        DN dn = new DN("cn=barbara,dc=Isode,c=US+o=isode, l=\\+\\+\\+, description=babs+sn=jensen");
  String str = dn.toString();
  String oid = dn.toOIDString();
  System.out.println(str);
  System.out.println(oid);
  DN dn2 = new DN(oid);
  System.out.println(dn.equals(dn2));
      will display 
        cn=barbara,dc=Isode,o=isode+c=US,l=\+\+\+,description=babs+sn=jensen
  2.5.4.3=barbara, 0.9.2342.19200300.100.1.25=Isode, 2.5.4.10=isode+2.5.4.6=US, 2.5.4.7=\+\+\+, 2.5.4.13=babs+2.5.4.4=jensen
  true
      Returns:
      a String representation with OIDs being used for attribute names
      Since:
      14.6
      See Also:

    • getCanonicalString

      public String getCanonicalString() throws NativeLibraryException
      Obtain a canonical String representation of this DN. The value returned will be identical to any other canonical representation of an equivalent DN value, even if the String representations differ. For example, the DN "cn=BABS         JENSEN,c=us" will have the same canonical string representation as that for "cn=babs jensen,c=us".

      This method may be useful for callers wishing e.g. to use DNs as keys for a HashSet, for which values returned by toString() or hashCode() are unsuitable.

      Users should not make assumptions about the format of String values returned by this method, but may safely make comparisons between canonical Strings for the purposes of testing DN equivalence.

      A String returned by this method may be used as a parameter to DN(String), in which case the object created will represent an equivalent DN to the original value, albeit one which may not have an identical String representation. For example 

       String s1 = "cn=BABS         JENSEN,c=us";
 DN dn1 = new DN(s1);
 String c1 = dn1.getCanonicalString();
 DN dn2 = new DN(c1);
 System.out.println(dn1.equals(dn2)); // DNs are equivalent
 System.out.println(dn1.toString().equals(dn2.toString()); // String representation may not be equivalent
      will display 
       true
 false
      (since canonicalising "cn=BABS         JENSEN,c=us" will result in embedded white space being condensed to a single space, among other things.)
      Returns:
      a canonical String representation of this DN.
      Throws:
      NativeLibraryException - if an unrecoverable error was detected by the native library
      Since:
      14.6
      See Also: