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

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

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[])

Class LdapUtils

Method Summary

Methods inherited from class java.lang.Object

Method Detail

closeContext

convertLdapException

getActualTargetClass

collectAttributeValues

collectAttributeValues

iterateAttributeValues

convertCompositeNameToString

newLdapName

newLdapName

removeFirst

prepend

emptyLdapName

getRdn

getValue

getValue

getStringValue

getStringValue

convertBinarySidToString

convertStringSidToBinary