org.springframework.ldap.support

## Class LdapUtils

- java.lang.Object
- - org.springframework.ldap.support.LdapUtils

-     public final class LdapUtils
      extends Object

  Generic utility methods for working with LDAP. Mainly for internal use within the framework, but also useful for custom code.
  Since:
    1.2
  Author:
    Ulrik Sandberg, Mattias Hellborg Arthursson

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `closeContext(DirContext context)` Close the given JNDI Context and ignore any thrown exception.
    `static void` | `collectAttributeValues(Attributes attributes, String name, Collection<Object> collection)` Collect all the values of a the specified attribute from the supplied Attributes.
    `static <T> void` | `collectAttributeValues(Attributes attributes, String name, Collection<T> collection, Class<T> clazz)` Collect all the values of a the specified attribute from the supplied Attributes as the specified class.
    `static String` | `convertBinarySidToString(byte[] sid)` Converts a binary SID to its String representation, according to the algorithm described here.
    `static String` | `convertCompositeNameToString(CompositeName compositeName)` Converts a CompositeName to a String in a way that avoids escaping problems, such as the dreaded "triple backslash" problem.
    `static NamingException` | `convertLdapException(NamingException ex)` Convert the specified checked `NamingException` to a Spring LDAP runtime `NamingException` equivalent.
    `static byte[]` | `convertStringSidToBinary(String string)` Converts a String SID to its binary representation, according to the algorithm described here.
    `static LdapName` | `emptyLdapName()` Construct a new, empty LdapName instance.
    `static Class` | `getActualTargetClass(DirContext context)` Get the actual class of the supplied DirContext instance; LdapContext or DirContext.
    `static Rdn` | `getRdn(Name name, String key)` Find the Rdn with the requested key in the supplied Name.
    `static String` | `getStringValue(Name name, int index)` Get the value of the Rdn at the requested index in the supplied Name as a String.
    `static String` | `getStringValue(Name name, String key)` Get the value of the Rdn with the requested key in the supplied Name as a String.
    `static Object` | `getValue(Name name, int index)` Get the value of the Rdn at the requested index in the supplied Name.
    `static Object` | `getValue(Name name, String key)` Get the value of the Rdn with the requested key in the supplied Name.
    `static void` | `iterateAttributeValues(Attribute attribute, AttributeValueCallbackHandler callbackHandler)` Iterate through all the values of the specified Attribute calling back to the specified callbackHandler.
    `static LdapName` | `newLdapName(Name name)` Construct a new LdapName instance from the supplied Name instance.
    `static LdapName` | `newLdapName(String distinguishedName)` Construct a new LdapName instance from the supplied distinguished name string.
    `static LdapName` | `prepend(Name dn, Name pathToPrepend)` Prepend the supplied path in the beginning the specified `Name` if the name instance starts with `path`.
    `static LdapName` | `removeFirst(Name dn, Name pathToRemove)` Remove the supplied path from the beginning the specified `Name` if the name instance starts with `path`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### closeContext

          public static void closeContext(DirContext context)

      Close the given JNDI Context and ignore any thrown exception. This is useful for typical `finally` blocks in JNDI code.
      Parameters:
        `context` - the JNDI Context to close (may be `null`)

    - #### convertLdapException

          public static NamingException convertLdapException(NamingException ex)

      Convert the specified checked `NamingException` to a Spring LDAP runtime `NamingException` equivalent.
      Parameters:
        `ex` - the original checked NamingException to convert
      Returns:
        the Spring LDAP runtime NamingException wrapping the given exception

    - #### getActualTargetClass

          public static Class getActualTargetClass(DirContext context)

      Get the actual class of the supplied DirContext instance; LdapContext or DirContext.
      Parameters:
        `context` - the DirContext instance to check.
      Returns:
        LdapContext.class if context is an LdapContext, DirContext.class otherwise.

    - #### collectAttributeValues

          public static void collectAttributeValues(Attributes attributes,
                                                    String name,
                                                    Collection<Object> collection)

      Collect all the values of a the specified attribute from the supplied Attributes.
      Parameters:
        `attributes` - The Attributes; not `null`.
        `name` - The name of the Attribute to get values for.
        `collection` - the collection to collect the values in.
      Throws:
        `NoSuchAttributeException` - if no attribute with the specified name exists.
      Since:
        1.3

    - #### collectAttributeValues

          public static <T> void collectAttributeValues(Attributes attributes,
                                                        String name,
                                                        Collection<T> collection,
                                                        Class<T> clazz)

      Collect all the values of a the specified attribute from the supplied Attributes as the specified class.
      Parameters:
        `attributes` - The Attributes; not `null`.
        `name` - The name of the Attribute to get values for.
        `collection` - the collection to collect the values in.
        `clazz` - the class of the collected attribute values
      Throws:
        `NoSuchAttributeException` - if no attribute with the specified name exists.
        `IllegalArgumentException` - if an attribute value cannot be cast to the specified class.
      Since:
        2.0

    - #### iterateAttributeValues

          public static void iterateAttributeValues(Attribute attribute,
                                                    AttributeValueCallbackHandler callbackHandler)

      Iterate through all the values of the specified Attribute calling back to the specified callbackHandler.
      Parameters:
        `attribute` - the Attribute to work with; not `null`.
        `callbackHandler` - the callbackHandler; not `null`.
      Since:
        1.3

    - #### convertCompositeNameToString

          public static String convertCompositeNameToString(CompositeName compositeName)

      Converts a CompositeName to a String in a way that avoids escaping problems, such as the dreaded "triple backslash" problem.
      Parameters:
        `compositeName` - The CompositeName to convert
      Returns:
        String containing the String representation of `name`

    - #### newLdapName

          public static LdapName newLdapName(Name name)

      Construct a new LdapName instance from the supplied Name instance. LdapName instances will be cloned, CompositeName tweaks will be managed using `convertCompositeNameToString(javax.naming.CompositeName)`; for all other Name implementations, new LdapName instances are constructed using `LdapName.addAll(int, javax.naming.Name)`.
      Parameters:
        `name` - the Name instance to convert to LdapName, not `null`.
      Returns:
        a new LdapName representing the same Distinguished Name as the supplied instance.
      Throws:
        `InvalidNameException` - to wrap any InvalidNameExceptions thrown by LdapName.
      Since:
        2.0

    - #### newLdapName

          public static LdapName newLdapName(String distinguishedName)

      Construct a new LdapName instance from the supplied distinguished name string.
      Parameters:
        `distinguishedName` - the string to parse for constructing an LdapName instance.
      Returns:
        a new LdapName instance.
      Throws:
        `InvalidNameException` - to wrap any InvalidNameExceptions thrown by LdapName.
      Since:
        2.0

    - #### removeFirst

          public static LdapName removeFirst(Name dn,
                                             Name pathToRemove)

      Remove the supplied path from the beginning the specified `Name` if the name instance starts with `path`. Useful for stripping base path suffix from a `Name`. The original Name will not be affected.
      Parameters:
        `dn` - the dn to strip from.
        `pathToRemove` - the path to remove from the beginning the dn instance.
      Returns:
        an LdapName instance that is a copy of the original name with the specified path stripped from its beginning.
      Since:
        2.0

    - #### prepend

          public static LdapName prepend(Name dn,
                                         Name pathToPrepend)

      Prepend the supplied path in the beginning the specified `Name` if the name instance starts with `path`. The original Name will not be affected.
      Parameters:
        `dn` - the dn to strip from.
        `pathToPrepend` - the path to prepend in the beginning of the dn.
      Returns:
        an LdapName instance that is a copy of the original name with the specified path inserted at its beginning.
      Since:
        2.0

    - #### emptyLdapName

          public static LdapName emptyLdapName()

      Construct a new, empty LdapName instance.
      Returns:
        a new LdapName instance representing the empty path ("").
      Since:
        2.0

    - #### getRdn

          public static Rdn getRdn(Name name,
                                   String key)

      Find the Rdn with the requested key in the supplied Name.
      Parameters:
        `name` - the Name in which to search for the key.
        `key` - the attribute key to search for.
      Returns:
        the rdn corresponding to the first occurrence of the requested key.
      Throws:
        `NoSuchElementException` - if no corresponding entry is found.
      Since:
        2.0

    - #### getValue

          public static Object getValue(Name name,
                                        String key)

      Get the value of the Rdn with the requested key in the supplied Name.
      Parameters:
        `name` - the Name in which to search for the key.
        `key` - the attribute key to search for.
      Returns:
        the value of the rdn corresponding to the first occurrence of the requested key.
      Throws:
        `NoSuchElementException` - if no corresponding entry is found.
      Since:
        2.0

    - #### getValue

          public static Object getValue(Name name,
                                        int index)

      Get the value of the Rdn at the requested index in the supplied Name.
      Parameters:
        `name` - the Name to work on.
        `index` - The 0-based index of the rdn value to retrieve. Must be in the range [0,size()).
      Returns:
        the value of the rdn at the requested index.
      Throws:
        `IndexOutOfBoundsException` - if index is outside the specified range.
      Since:
        2.0

    - #### getStringValue

          public static String getStringValue(Name name,
                                              int index)

      Get the value of the Rdn at the requested index in the supplied Name as a String.
      Parameters:
        `name` - the Name to work on.
        `index` - The 0-based index of the rdn value to retrieve. Must be in the range [0,size()).
      Returns:
        the value of the rdn at the requested index as a String.
      Throws:
        `IndexOutOfBoundsException` - if index is outside the specified range.
        `ClassCastException` - if the value of the requested component is not a String.
      Since:
        2.0

    - #### getStringValue

          public static String getStringValue(Name name,
                                              String key)

      Get the value of the Rdn with the requested key in the supplied Name as a String.
      Parameters:
        `name` - the Name in which to search for the key.
        `key` - the attribute key to search for.
      Returns:
        the String value of the rdn corresponding to the first occurrence of the requested key.
      Throws:
        `NoSuchElementException` - if no corresponding entry is found.
        `ClassCastException` - if the value of the requested component is not a String.
      Since:
        2.0

    - #### convertBinarySidToString

          public static String convertBinarySidToString(byte[] sid)

      Converts a binary SID to its String representation, according to the algorithm described here. Thanks to Eyal Lupu for algorithmic inspiration.

           If you have a SID like S-a-b-c-d-e-f-g-...

           Then the bytes are
           a      (revision)
           N      (number of dashes minus two)
           bbbbbb (six bytes of "b" treated as a 48-bit number in big-endian format)
           cccc   (four bytes of "c" treated as a 32-bit number in little-endian format)
           dddd   (four bytes of "d" treated as a 32-bit number in little-endian format)
           eeee   (four bytes of "e" treated as a 32-bit number in little-endian format)
           ffff   (four bytes of "f" treated as a 32-bit number in little-endian format)
           etc.

           So for example, if your SID is S-1-5-21-2127521184-1604012920-1887927527-72713, then your raw hex SID is

           010500000000000515000000A065CF7E784B9B5FE77C8770091C0100

           This breaks down as follows:
           01     S-1
           05     (seven dashes, seven minus two = 5)
           000000000005   (5 = 0x000000000005, big-endian)
           15000000       (21 = 0x00000015, little-endian)
           A065CF7E       (2127521184 = 0x7ECF65A0, little-endian)
           784B9B5F       (1604012920 = 0x5F9B4B78, little-endian)
           E77C8770       (1887927527 = 0X70877CE7, little-endian)
           091C0100       (72713 = 0x00011c09, little-endian)

           S-1-   version number (SID_REVISION)
           -5-    SECURITY_NT_AUTHORITY
           -21-   SECURITY_NT_NON_UNIQUE
           -...-...-...-  these identify the machine that issued the SID
           72713  unique user id on the machine

      Parameters:
        `sid` - binary SID in byte array format
      Returns:
        String version of the given sid
      Since:
        1.3.1

    - #### convertStringSidToBinary

          public static byte[] convertStringSidToBinary(String string)

      Converts a String SID to its binary representation, according to the algorithm described here.
      Parameters:
        `string` - SID in readable format
      Returns:
        Binary version of the given sid
      Since:
        1.3.1
      See Also:
        `convertBinarySidToString(byte[])`