com.ca.jcs.util
Class LdapUtil

java.lang.Object
  com.ca.jcs.util.LdapUtil

public abstract class LdapUtil
extends Object

LDAP related utilities.

Field Summary

static String	LDAP_OBJECT_CLASS Reserved name to represent an object's type in LDAP.
static String[]	LDAP_OBJECT_CLASS_ARR Array that can be passed in to lookup() / search return attrs when only interested in object's type.
static String	LDAP_OBJECT_CLASS_OID Object IDentifier (OID) for LDAP_OBJECT_CLASS.
static String	NOT_SHOWN Should be output to show that sensitive attributes have a value, without showing the value itself.
static String[]	TEST_EXISTANCE_ATTRS Array that can be passed in to lookup() / search return attrs when only interested in whether an object exists or not.

Constructor Summary

LdapUtil()

Method Summary

static void	addAttributeValues(Attribute attr, Collection vals) Calls addAttributeValues(Attribute, Collection, boolean) with toString=false.
static void	addAttributeValues(Attribute attr, Collection vals, boolean toString) Adds values in vals to attr.
static void	addAttrValue(Attribute attr, Object val)
static void	addAttrValue(Attributes attrs, String attrId, Object val)
static boolean	allAttributesExist(Attributes attrs, Collection<String> attrIds)
static String	appendNameComponent(String baseName, String addComponent)
static void	checkAttrsNotNull(Logger log, Object name, Attributes attrs, boolean strict) Attributes with no values upset connectors on the way in and cause the ApacheDS LDAP codec to hang on the way out.
static void	checkAttrsValid(Logger log, Object name, Attributes attrs) the default behaviour is to report error if any bad attributes found
static void	checkAttrsValid(Logger log, Object name, Attributes attrs, boolean strict) Attributes with no values upset connectors on the way in and cause the ApacheDS LDAP codec to hang on the way out.
static SearchControls	cloneSearchControls(SearchControls sc)
static Attribute	computeAddedDelta(Attribute currValue, Attribute newValue) Compute values which need to be added to currValue in order for it to match newValue.
static Attribute	computeDeletedDelta(Attribute currValue, Attribute newValue) Compute values which need to be deleted from currValue in order for it to match newValue.
static Attribute	copyAttribute(String newId, Attribute attr) Return a copy of attr with a new id, if newId is null then attr's id will be used.
static Attribute	createAttributeFromValue(String attrId, Object val)
static Attribute	createAttributeFromValueList(String attrId, List vals)
static Attributes	deepCloneAttributes(Attributes attrs)
static boolean	dnStartsWith(Name name, Name subName, boolean caseSensitive) Compare two DNs, and see whether it starts with the specified base DN.
static String[]	ensureAttrIdInList(String[] attrIds, String attrId) Check if attrId is in the provided array, and if not then add it.
static String	escapeCompositeName(String compName) Implements escaping rules described in CompositeName.
static String	escapeNonAscii(String input) Escapes non-ascii characters in LDAP filters, as per RFC2254
static String	extractDeepestRdnValue(String dn) Extract deepest RDN value in the DN and strip of RDN name attribute
static String	filterEscape(String val) Simply wraps JNDIUtil.filterEscape(String) to make life easier for scripts and code in general by avoiding import, and also calls escapeNonAscii(String).
static String	getAttrFromDN(Name baseName, String attrId) Helper method to search an Ldap DN and return a specific attributes values from the rdn list
static String	getAttributeNameFromRDN(String rdnStr) Get "var" in a var=val component of an LDAP JNDI Name, accounting for RDN quoting rules.
static Attributes	getAttributes(Attributes attrs, String[] ldapAttrIds)
static String	getAttributeValueFromRDN(String rdnStr) Get "val" in a var=val component of an LDAP JNDI Name, accounting for RDN quoting rules.
static String	getAttributeValueFromRDN(String rdnStr, String attrId, boolean deepest) Get "val" in a var=val component of an LDAP JNDI Name, accounting for RDN quoting rules but look for user specified RDN name match.
static List	getAttributeValueList(Attribute attr) Calls getAttributeValueList(Attribute, boolean) with toString=false.
static List	getAttributeValueList(Attribute attr, boolean toString) Return list with length attr.size() containing attr's values (may be 0 length).
static String[]	getAttributeValues(Attribute attr) Return array with length attr.size() containing attr's values (may be 0 length).
static String[]	getAttributeValues(Attribute attr, boolean lowercase)
static String	getAttrValue(Attributes attrs, String attrId) Return string value for named attribute.
static String[]	getAttrValues(Attributes attrs, String attrId)
static String	getDeepestRDN(String dn)
static int	getIntAttr(Attributes attrs, String attrId, int def) Return int value of attribute named attrId in attrs, or def if it is not present.
static Rdn	getRDN(String rdnStr) Return RDN containing both attribute name and value for LDAP name component, accounting for RDN quoting rules and also extra flexible SimpleLdapName support.
static Rdn	getRDN(String rdnStr, boolean deepest) Return both attribute name and value for LDAP name component, accounting for RDN quoting rules, deepest controls whether most deeply nested RDN is requested.
static Rdn	getRDN(String rdnStr, String attrId, boolean deepest) Same as getRDN(String), but look for and return user specified RDN component in a DN identified by attrId.
static String	getRDNString(String attrId, String attrValue) Create an RDN (Relative Distinguished Name) using the provided attrId, and applying RFC 2253 quoting rules to the provided attrValue.
static String	getRDNString(String attrId, String attrValue, boolean composite)
static String	getStrAttr(Attributes attrs, String attrId, String def) Return value of attribute named attrId in attrs as a string, or def if it is not present.
static String	getValueCommaList(Attribute attr)
static String	getValueList(Attribute attr)
static String	getValueList(Attribute attr, String sep, String quote)
static boolean	isAttributeRequested(String[] attrIds, String attr)
static boolean	isAttributeRequested(String[] attrIds, String attr, boolean ignoreCase) Returns true if the 'attr' is contained within the 'attrIds'.
static boolean	isAttrIdInList(String ldapAttrId, List<String> attrIdList)
static boolean	isExistanceAttrs(String[] attrIds) Test if attrIds corresponds to TEST_EXISTANCE_ATTRS
static boolean	isObjectClass(String attrId)
static String	joinAttrs(Attributes attrs, String sep, String[] joinAttrIds) Joins the values of the attribute ids named in joinAttrIds, within attrs, separated by sep.
static void	main(String[] args)
static void	mergeAttribute(Attribute attr, Attribute deltaAttr)
static void	mergeAttributes(Attributes origAttrs, Attributes newAttrs)
static Attribute	modifyAttribute(Attribute attr, ModificationItem item) Handle applying item to attr, which it targets.
static Attributes	modifyAttributes(Attributes attrs, ModificationItem[] items) Handle applying the provided items to attrs.
static String	normalize(String s) The ADS codec converts all strings to lowercase.
static String	removeAttrValue(Attribute attrToUpdate, String value) Needed for cases like where CA directory is queried for groups matching '(member=myDn)' but then returned group.member value contains myDn with a different case (ie searched for cn=BLB,ou=LOFBE01,ou=eTrust Admin,o=democorp,c=AU and resulting DN considered to match was cn=BLB,ou=LOFBE01,ou=eTrust Admin,o=DEMOCORP,c=AU.
static String	searchControlsToString(SearchControls sc) Simply wraps JNDIUtil.searchControlsToString(SearchControls) to make life easier for scripts and code in general by avoiding import.
static void	setAttrValue(Attribute attr, Object val)
static void	setAttrValueList(Attribute attr, List vals)
static void	setDefensiveLimits(SearchControls searchControls) Lotus Notes Directory (LND) seems to treat countLimit=0 as countLimit=1, so we'll program defensively.
static String	unescapeCompositeName(String compName) Does reverse of escaping rules described in CompositeName, required as JNDI client returns composite names for search results.

Methods inherited from class java.lang.Object

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

Field Detail

NOT_SHOWN

public static final String NOT_SHOWN

Should be output to show that sensitive attributes have a value, without showing the value itself.

See Also:

Constant Field Values

LDAP_OBJECT_CLASS

public static final String LDAP_OBJECT_CLASS

Reserved name to represent an object's type in LDAP.

See Also:

Constant Field Values

LDAP_OBJECT_CLASS_ARR

public static final String[] LDAP_OBJECT_CLASS_ARR

Array that can be passed in to lookup() / search return attrs when only interested in object's type.

LDAP_OBJECT_CLASS_OID

public static final String LDAP_OBJECT_CLASS_OID

Object IDentifier (OID) for LDAP_OBJECT_CLASS.

See Also:

Constant Field Values

TEST_EXISTANCE_ATTRS

public static final String[] TEST_EXISTANCE_ATTRS

Array that can be passed in to lookup() / search return attrs when only interested in whether an object exists or not. Refer isExistanceAttrs(String[])

Constructor Detail

LdapUtil

public LdapUtil()

Method Detail

checkAttrsValid

public static void checkAttrsValid(Logger log,
                                   Object name,
                                   Attributes attrs,
                                   boolean strict)
                            throws NamingException

Attributes with no values upset connectors on the way in and cause the ApacheDS LDAP codec to hang on the way out. The LDAP v2 and v3 RFCs are not particularly clear on whether such attributes can be stored, but the general feeling seems to be that v3 allows directory strings to store "". However most servers strip them out and the eTrust Directory gurus recommended doing the same. Note this case is also problematic for JDBC connector talking to Oracle, which treats "" as NULL. If it is inbound direction (from Admin to connector), in some cases we don't want it to throw Exception even if bad attributes are found.

Throws:

NamingException

checkAttrsNotNull

public static void checkAttrsNotNull(Logger log,
                                     Object name,
                                     Attributes attrs,
                                     boolean strict)
                              throws NamingException

Attributes with no values upset connectors on the way in and cause the ApacheDS LDAP codec to hang on the way out. The LDAP v2 and v3 RFCs are not particularly clear on whether such attributes can be stored, but the general feeling seems to be that v3 allows directory strings to store "". However most servers strip them out and the eTrust Directory gurus recommended doing the same. Note this case is also problematic for JDBC connector talking to Oracle, which treats "" as NULL.

If it is inbound direction (from Admin to connector), in some cases we don't want it to throw Exception even if bad attributes are found.

Throws:

NamingException

checkAttrsValid

public static void checkAttrsValid(Logger log,
                                   Object name,
                                   Attributes attrs)
                            throws NamingException

the default behaviour is to report error if any bad attributes found

Throws:

NamingException

getAttributeValues

public static String[] getAttributeValues(Attribute attr,
                                          boolean lowercase)

getAttributeValues

public static String[] getAttributeValues(Attribute attr)

Return array with length attr.size() containing attr's values (may be 0 length).

getAttributeValueList

public static List getAttributeValueList(Attribute attr)

Calls getAttributeValueList(Attribute, boolean) with toString=false.

getAttributeValueList

@NotNull
public static List getAttributeValueList(Attribute attr,
                                                 boolean toString)

Return list with length attr.size() containing attr's values (may be 0 length). If toString==true then the toString() of each value is returned instead.

createAttributeFromValue

public static Attribute createAttributeFromValue(String attrId,
                                                 Object val)

setAttrValue

public static void setAttrValue(Attribute attr,
                                Object val)

createAttributeFromValueList

public static Attribute createAttributeFromValueList(String attrId,
                                                     List vals)

setAttrValueList

public static void setAttrValueList(Attribute attr,
                                    List vals)

addAttributeValues

public static void addAttributeValues(@NotNull
                                      Attribute attr,
                                      @Nullable
                                      Collection vals,
                                      boolean toString)

Adds values in vals to attr. If\ toString==true then the toString() of each value is returned instead.

addAttributeValues

public static void addAttributeValues(@NotNull
                                      Attribute attr,
                                      @Nullable
                                      Collection vals)

Calls addAttributeValues(Attribute, Collection, boolean) with toString=false.

mergeAttribute

public static void mergeAttribute(Attribute attr,
                                  Attribute deltaAttr)
                           throws NamingException

Throws:

NamingException

allAttributesExist

public static boolean allAttributesExist(Attributes attrs,
                                         Collection<String> attrIds)

setDefensiveLimits

public static void setDefensiveLimits(SearchControls searchControls)

Lotus Notes Directory (LND) seems to treat countLimit=0 as countLimit=1, so we'll program defensively.

isAttrIdInList

public static boolean isAttrIdInList(String ldapAttrId,
                                     List<String> attrIdList)

isExistanceAttrs

public static boolean isExistanceAttrs(String[] attrIds)

Test if attrIds corresponds to TEST_EXISTANCE_ATTRS

ensureAttrIdInList

public static String[] ensureAttrIdInList(String[] attrIds,
                                          String attrId)

Check if attrId is in the provided array, and if not then add it.

Returns:

Possibly expanded array.

getAttrValue

public static String getAttrValue(Attributes attrs,
                                  String attrId)

Return string value for named attribute.

See Also:

getStrAttr(Attributes, String, String)

getAttrValues

public static String[] getAttrValues(Attributes attrs,
                                     String attrId)

addAttrValue

public static void addAttrValue(Attribute attr,
                                Object val)

addAttrValue

public static void addAttrValue(Attributes attrs,
                                String attrId,
                                Object val)

removeAttrValue

public static String removeAttrValue(Attribute attrToUpdate,
                                     String value)
                              throws NamingException

Needed for cases like where CA directory is queried for groups matching '(member=myDn)' but then returned group.member value contains myDn with a different case (ie searched for cn=BLB,ou=LOFBE01,ou=eTrust Admin,o=democorp,c=AU and resulting DN considered to match was cn=BLB,ou=LOFBE01,ou=eTrust Admin,o=DEMOCORP,c=AU. Note that Sun and ApacheDS implementations of Attribute.remove(Object) don't ignore case, hence the need for this method to handle the described case.

Parameters:

attrToUpdate - Attribute which should have a value removed.

value - Value to remove.

Returns:

Matched string if value was found (ignoring case) and removed.

Throws:

NamingException

getValueList

public static String getValueList(Attribute attr,
                                  String sep,
                                  String quote)

getValueCommaList

public static String getValueCommaList(Attribute attr)

getValueList

public static String getValueList(Attribute attr)

computeAddedDelta

public static Attribute computeAddedDelta(Attribute currValue,
                                          Attribute newValue)

Compute values which need to be added to currValue in order for it to match newValue.

Parameters:

currValue - Current value.

newValue - Desired value.

Returns:

Values which need to be added, or null if values in newValue are <= values in currValue.

computeDeletedDelta

public static Attribute computeDeletedDelta(Attribute currValue,
                                            Attribute newValue)

Compute values which need to be deleted from currValue in order for it to match newValue.

Parameters:

currValue - Current value.

newValue - Desired value.

Returns:

Values which need to be deleted, or null if values in newValue are >= values in currValue.

isObjectClass

public static boolean isObjectClass(String attrId)

getAttributeNameFromRDN

public static String getAttributeNameFromRDN(String rdnStr)
                                      throws InvalidNameException

Get "var" in a var=val component of an LDAP JNDI Name, accounting for RDN quoting rules.

Throws:

InvalidNameException

getAttributeValueFromRDN

public static String getAttributeValueFromRDN(String rdnStr)
                                       throws InvalidNameException

Get "val" in a var=val component of an LDAP JNDI Name, accounting for RDN quoting rules.

Throws:

InvalidNameException

getAttributeValueFromRDN

public static String getAttributeValueFromRDN(String rdnStr,
                                              String attrId,
                                              boolean deepest)
                                       throws InvalidNameException

Get "val" in a var=val component of an LDAP JNDI Name, accounting for RDN quoting rules but look for user specified RDN name match.

Throws:

InvalidNameException

getRDN

public static Rdn getRDN(String rdnStr)
                  throws InvalidNameException

Return RDN containing both attribute name and value for LDAP name component, accounting for RDN quoting rules and also extra flexible SimpleLdapName support.

Throws:

InvalidNameException

getRDN

public static Rdn getRDN(String rdnStr,
                         boolean deepest)
                  throws InvalidNameException

Return both attribute name and value for LDAP name component, accounting for RDN quoting rules, deepest controls whether most deeply nested RDN is requested.

Throws:

InvalidNameException

getRDN

public static Rdn getRDN(String rdnStr,
                         String attrId,
                         boolean deepest)
                  throws InvalidNameException

Same as getRDN(String), but look for and return user specified RDN component in a DN identified by attrId. First match is returned, deepest specifies whether first or last component is returned.

Throws:

InvalidNameException

getRDNString

public static String getRDNString(String attrId,
                                  String attrValue,
                                  boolean composite)

dnStartsWith

public static boolean dnStartsWith(Name name,
                                   Name subName,
                                   boolean caseSensitive)

Compare two DNs, and see whether it starts with the specified base DN. If it is not case sensitive, it needs to compare each name one by one.

Parameters:

name - the long DN

subName - the sub DN

caseSensitive - is case sensitive?

Returns:

true if the long DN start with the base DN.

getRDNString

public static String getRDNString(String attrId,
                                  String attrValue)

Create an RDN (Relative Distinguished Name) using the provided attrId, and applying RFC 2253 quoting rules to the provided attrValue. It is very important that connectors create RDNs using this method rather then trying to do a simple concatenation themselves, due to the need to escape attrValue!

Parameters:

attrId - Attribute identifier to be used in RDN.

attrValue - Value to be used in RDN (escaping may be required)

Returns:

Resulting RDN.

normalize

public static String normalize(String s)

The ADS codec converts all strings to lowercase.

getDeepestRDN

public static String getDeepestRDN(String dn)

Returns:

Mostly deeply nested RDN in provided DN, accounting for RDN quoting rules.

extractDeepestRdnValue

public static String extractDeepestRdnValue(String dn)

Extract deepest RDN value in the DN and strip of RDN name attribute

Parameters:

dn - DN to extract from

Returns:

deepest RDN value

appendNameComponent

public static String appendNameComponent(String baseName,
                                         String addComponent)

mergeAttributes

public static void mergeAttributes(Attributes origAttrs,
                                   Attributes newAttrs)

copyAttribute

public static Attribute copyAttribute(String newId,
                                      Attribute attr)

Return a copy of attr with a new id, if newId is null then attr's id will be used. Returns null if attr==null.

modifyAttribute

public static Attribute modifyAttribute(Attribute attr,
                                        ModificationItem item)
                                 throws NamingException

Handle applying item to attr, which it targets.

Throws:

NamingException

modifyAttributes

public static Attributes modifyAttributes(Attributes attrs,
                                          ModificationItem[] items)
                                   throws NamingException

Handle applying the provided items to attrs.

Throws:

NamingException

getAttributes

public static Attributes getAttributes(Attributes attrs,
                                       String[] ldapAttrIds)
                                throws NamingException

Throws:

NamingException

getAttrFromDN

public static String getAttrFromDN(Name baseName,
                                   String attrId)

Helper method to search an Ldap DN and return a specific attributes values from the rdn list

Parameters:

baseName -

attrId -

Returns:

value

isAttributeRequested

public static boolean isAttributeRequested(String[] attrIds,
                                           String attr,
                                           boolean ignoreCase)

Returns true if the 'attr' is contained within the 'attrIds'. Can be used to determine if a particular attribute is requested.

Parameters:

attrIds -

attr -

Returns:

true if attribute is in attrIds list

isAttributeRequested

public static boolean isAttributeRequested(String[] attrIds,
                                           String attr)

Returns:

Result of calling isAttributeRequested(String[], String, boolean) with false as the last argument.

deepCloneAttributes

public static Attributes deepCloneAttributes(Attributes attrs)
                                      throws NamingException

Throws:

NamingException

cloneSearchControls

public static SearchControls cloneSearchControls(SearchControls sc)

searchControlsToString

public static String searchControlsToString(SearchControls sc)

Simply wraps JNDIUtil.searchControlsToString(SearchControls) to make life easier for scripts and code in general by avoiding import.

escapeNonAscii

public static String escapeNonAscii(String input)

Escapes non-ascii characters in LDAP filters, as per RFC2254

filterEscape

public static String filterEscape(String val)

Simply wraps JNDIUtil.filterEscape(String) to make life easier for scripts and code in general by avoiding import, and also calls escapeNonAscii(String).

escapeCompositeName

public static String escapeCompositeName(String compName)

Implements escaping rules described in CompositeName. eg. cn=foo/bar to be escaped to be "cn=foo/bar" to avoid it to be interpreted as a composite name consisting of "foo" and "bar" otherwise.

Parameters:

compName - Composite name to be escaped.

Returns:

Escaped version of compName

unescapeCompositeName

public static String unescapeCompositeName(String compName)

Does reverse of escaping rules described in CompositeName, required as JNDI client returns composite names for search results. Note that unescaping a composite name which is not been escaped is considered an error and will return null

Parameters:

compName - String representation composite name to be unescaped.

Returns:

Escaped version of compName

main

public static void main(String[] args)

getIntAttr

public static int getIntAttr(Attributes attrs,
                             String attrId,
                             int def)

Return int value of attribute named attrId in attrs, or def if it is not present.

getStrAttr

public static String getStrAttr(Attributes attrs,
                                String attrId,
                                String def)

Return value of attribute named attrId in attrs as a string, or def if it is not present.

See Also:

getAttrValue(Attributes, String)

joinAttrs

public static String joinAttrs(Attributes attrs,
                               String sep,
                               String[] joinAttrIds)
                        throws NamingException

Joins the values of the attribute ids named in joinAttrIds, within attrs, separated by sep. Any missing values are simply skipped.

Throws:

NamingException