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

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