Package com.isode.dsapi

Class DN

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<DN>, java.lang.Iterable<RDN>
    public class DN
extends java.lang.Object
implements java.lang.Comparable<DN>, java.lang.Iterable<RDN>, java.io.Serializable
    Class representing a Distinguished Name.
    See Also:
    Serialized Form

    • 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​(java.lang.String dnStr)
      Constructor from LDAP formatted string DN.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(DN other)
      Compare two DNs.
      boolean equals​(java.lang.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
      java.lang.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.
      java.util.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.
      java.lang.String toOIDString()
      Generate a String representation of the DN, including dotted OID values instead of attribute names.
      java.lang.String toString()
      Return a String representation of the DN, containing attribute names and values.
      java.lang.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 Detail

      • 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​(java.lang.String dnStr)
   throws BadDNException,
          NativeLibraryException,
          java.lang.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
        java.lang.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 Detail

      • 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 java.lang.Throwable
        Releases any native structures associated with this object.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.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:
        java.lang.NullPointerException - if rdn is null
        NativeLibraryException - if an unrecoverable error was detected by the native library

      • isSameValue

        public boolean isSameValue​(DN value)
                    throws java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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 java.lang.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()

      • toString

        public final java.lang.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 java.lang.Object
        Returns:
        String representation of DN.
        Throws:
        NativeLibraryException - if an unrecoverable error was detected by the native library
        See Also:
        DN(String)

      • equals

        public boolean equals​(java.lang.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 java.lang.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 java.lang.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 java.lang.Object
        Returns:
        a hash code value for the DN.
        See Also:
        getCanonicalString()

      • iterator

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

      • toOIDString

        public java.lang.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:
        toString(), toUIString(), RDN.toOIDString()

      • getCanonicalString

        public java.lang.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:
        hashCode()