Skip navigation links

oracle.idm.connection.ldap
Class LdapContextManager

java.lang.Object
oracle.idm.connection.ldap.LdapContextManager

All Implemented Interfaces:

LdapContextDelegate, XmlPrintable

public class LdapContextManager

extends java.lang.Object

implements LdapContextDelegate

This class implements the LDAP context manager.

This this class observes the following IdM Connection parameters to LDAP Context environment mapping:

 IdM Connection Parameters           =>    LDAP Context Environment
 ==============================================================================
 Connection.Parameter.AUTHENTICATION =>    LdapContext.SECURITY_AUTHENTICATION
 Connection.Parameter.PROTOCOL       =>    LdapContext.SECURITY_PROTOCOL
 Connection.Parameter.PRINCIPAL      =>    LdapContext.SECURITY_PRINCIPAL
 Connection.Parameter.CREDENTIALS    =>    LdapContext.SECURITY_CREDENTIALS
 

The Connection.Parameter.PRINCIPAL and Connection.Parameter.CREDENTIALS parameters must be used consistently, meaning they must be specified or unspecified together.

The use of null parameter values is allowed, recomended, and required.

To get the connection identity specified in the initial environment, do not specify either Connection.Parameter.PRINCIPAL or Connection.Parameter.CREDENTIALS when requesting a connection from the pool

To get a different identity from the one specified in the initial environment, specify both Connection.Parameter.PRINCIPAL and Connection.Parameter.CREDENTIALS when requesting a connection from the pool.

To get an anonymous connection, specify both Connection.Parameter.PRINCIPAL and Connection.Parameter.CREDENTIALS values as null when requesting a connection from the pool.

Extend this class if any of the assumptions made by the methods listed below do not implement the desired behavior. I've tried to implement the most common cases, and give plenty of flexibility in how it can be applied.

When modifying LDAP context manager properties directly, synchronize with the connection pool in order to avoid undesirable side effects, as follows:

 synchronized (pool) { manager.setValidating(false); }
 

Field Summary

static boolean	DEFAULT_REPROXYING The default reproxying mode is true.
static boolean	DEFAULT_UNPROXYING The default unproxying mode is true.
protected java.lang.String	tag Tag used to print the object as an XML element.

Fields inherited from interface oracle.idm.connection.ldap.LdapContextDelegate

DEFAULT_PROXYING, DEFAULT_VALIDATING

Constructor Summary

LdapContextManager(java.util.Map environment, javax.naming.ldap.Control[] controls)
Constructor for the LDAP context manager.

Method Summary

boolean	canCloseLdapContext(javax.naming.ldap.LdapContext context, java.util.Map parameters) Returns true if the LDAP context can be closed.
boolean	canOpenLdapContext(java.util.Map parameters) This method determines if the LDAP Context can be opened using the specified IdM Connection parameters.
boolean	canProxyLdapContext(javax.naming.ldap.LdapContext context, java.util.Map parameters) This method determines if the LDAP Context can be proxied to match the specified IdM Connection parameters.
boolean	canValidateLdapContext(javax.naming.ldap.LdapContext context, java.util.Map parameters) Returns true if the LDAP context can be validated.
protected void	checkParameters(java.util.Map parameters, java.util.Map environment) Checks if parameters against environment for validity, called from actual operation methods.
java.util.Map	cloneEnvironment(java.util.Map environment) Clones environment and hides sensitive parameters.
protected static java.util.Hashtable	cloneHashtable(java.util.Map map) This method clones a Map into a Hashtable.
java.util.Map	cloneParameters(java.util.Map parameters) This method colones parameters to be internalized by the connection.
void	closeLdapContext(javax.naming.ldap.LdapContext context, java.util.Map parameters, int failSafeLevel) Closes the LDAP context.
protected static boolean	equal(java.lang.Object object1, java.lang.Object object2) Tests objects for equality, null pointer safe.
javax.naming.ldap.Control[]	getControls() Getter for the initial controls.
java.util.Map	getEnvironment() Getter for the initial environment map.
protected static java.lang.Object	getValue(java.util.Map map, java.lang.String key) Returns the value of the key from the map, null pointer safe.
boolean	isAlteredLdapContext(javax.naming.ldap.LdapContext context, java.util.Map environment) Returns true if this LDAP context environment is altered with regards to the one passed in.
boolean	isMatchingLdapContext(javax.naming.ldap.LdapContext context, java.util.Map parameters) This method matches the LDAP Context environment against the specified IdM Connection parameters.
boolean	isMatchingParameters(java.util.Map parameters) Tests if the ldap context delegate matches specified parameters.
protected boolean	isMatchingParameters(java.util.Map parameters, java.util.Map environment) Tests if the specified parameters match the specified environment.
boolean	isProxying() Getter for the proxying mode.
boolean	isReproxying() Getter for the reproxying mode.
protected static boolean	isSpecified(java.util.Map map, java.lang.String key) Returns true if key is contained in the map, null pointer safe.
boolean	isUnproxying() Getter for the unproxying mode.
boolean	isValidating() Getter for the validating mode.
protected java.lang.String	normalizeDn(java.lang.String dn) Normalizes distinsuished name for comparison purposes.
javax.naming.ldap.LdapContext	openLdapContext(java.util.Map parameters, int failSafeLevel) This method opens a new LDAP context.
void	proxyLdapContext(javax.naming.ldap.LdapContext context, java.util.Map parameters, int failSafeLevel) This method proxies the LDAP context.
void	resetProxying() Resets the proxying mode to DEFAULT_PROXYING.
void	resetReproxying() Resets the reproxying mode to DEFAULT_REPROXYING.
void	resetUnproxying() Resets the unproxying mode to DEFAULT_UNPROXYING.
void	resetValidating() Resets the validating mode to DEFAULT_VALIDATING.
protected void	setControls(javax.naming.ldap.Control[] controls) Setter for the initial controls.
protected void	setEnvironment(java.util.Map environment) Setter for the initial environment map.
void	setProxying(boolean proxying) Setter for the proxying mode.
void	setReproxying(boolean reproxying) Setter for the reproxying mode.
void	setUnproxying(boolean unproxying) Setter for the unproxying mode.
void	setValidating(boolean validating) Setter for the validating mode.
void	validateLdapContext(javax.naming.ldap.LdapContext context, java.util.Map parameters, int failSafeLevel) Validates the LDAP context.
void	xprint(XmlPrintWriter out) Prints LDAP context manager properties to the PrintWriter as an XML element.
protected void	xprintBody(XmlPrintWriter out) This method prints the LDAP context manager XML tag body.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_REPROXYING

public static final boolean DEFAULT_REPROXYING

The default reproxying mode is true.

See Also:

Constant Field Values

DEFAULT_UNPROXYING

public static final boolean DEFAULT_UNPROXYING

The default unproxying mode is true.

See Also:

Constant Field Values

tag

protected java.lang.String tag

Tag used to print the object as an XML element.

Constructor Detail

LdapContextManager

public LdapContextManager(java.util.Map environment,
                          javax.naming.ldap.Control[] controls)

Constructor for the LDAP context manager.

Method Detail

getEnvironment

public java.util.Map getEnvironment()

Getter for the initial environment map.

Returns:

the initial environment map

setEnvironment

protected void setEnvironment(java.util.Map environment)

Setter for the initial environment map.

getControls

public javax.naming.ldap.Control[] getControls()

Getter for the initial controls.

Returns:

the initial controls

setControls

protected void setControls(javax.naming.ldap.Control[] controls)

Setter for the initial controls.

isProxying

public boolean isProxying()

Description copied from interface: LdapContextDelegate

Getter for the proxying mode.

Specified by:

isProxying in interface LdapContextDelegate

Returns:

true if the ldap context delegate is proxying, false otherwise

setProxying

public void setProxying(boolean proxying)

Description copied from interface: LdapContextDelegate

Setter for the proxying mode.

Specified by:

setProxying in interface LdapContextDelegate

resetProxying

public void resetProxying()

Description copied from interface: LdapContextDelegate

Resets the proxying mode to DEFAULT_PROXYING.

Specified by:

resetProxying in interface LdapContextDelegate

isReproxying

public boolean isReproxying()

Getter for the reproxying mode.

Returns:

true if the LDAP context manager is reproxying, false otherwise

setReproxying

public void setReproxying(boolean reproxying)

Setter for the reproxying mode.

If reproxying is true, the LDAP context manager will allow repeated proxying from any identity to any identity.

If reproxying is false, the LDAP context manager will allow only proxying from the initial identity to the specified identity.

resetReproxying

public void resetReproxying()

Resets the reproxying mode to DEFAULT_REPROXYING.

isUnproxying

public boolean isUnproxying()

Getter for the unproxying mode.

Returns:

true if the LDAP context manager is unproxying, false otherwise

setUnproxying

public void setUnproxying(boolean unproxying)

Setter for the unproxying mode.

If unproxying is true, the LDAP context manager will allow proxying back to the initial identity specified in the initial environment. This is useful when the initial idenitity is anonymous, and one can always proxy back to it.

If unproxying is false, the LDAP context manager will not allow proxying back to the initial identity specified in the initial environment. This is useful when the initial identity is a superuser, and one cannot proxy back to it after it has been proxied to a less privileged user.

resetUnproxying

public void resetUnproxying()

Resets the unproxying mode to DEFAULT_UNPROXYING.

isValidating

public boolean isValidating()

Description copied from interface: LdapContextDelegate

Getter for the validating mode.

Specified by:

isValidating in interface LdapContextDelegate

Returns:

true if the ldap context delegate is validating, false otherwise

setValidating

public void setValidating(boolean validating)

Description copied from interface: LdapContextDelegate

Setter for the validating mode.

Specified by:

setValidating in interface LdapContextDelegate

resetValidating

public void resetValidating()

Description copied from interface: LdapContextDelegate

Resets the validating mode to DEFAULT_VALIDATING.

Specified by:

resetValidating in interface LdapContextDelegate

isMatchingParameters

public boolean isMatchingParameters(java.util.Map parameters)

Tests if the ldap context delegate matches specified parameters.

The following specified IdM Connection parameters must match the initial LDAP environment exactly, or this method will return false.

 IdM Connection Parameters           =>    LDAP Context Environment
 ==============================================================================
 Connection.Parameter.AUTHENTICATION =>    LdapContext.SECURITY_AUTHENTICATION
 Connection.Parameter.PROTOCOL       =>    LdapContext.SECURITY_PROTOCOL
 

If any of the IdM Connection parameters were not specified, they will not be matched against the initial LDAP environment, and assumed to be irrelevant.

Specifying a null value for any of the IdM Connection parameters will make sure the corresponding setting from the initial LDAP environment is unspecified.

Specified by:

isMatchingParameters in interface LdapContextDelegate

Returns:

true if the parameterts match, false otherwise

isMatchingParameters

protected boolean isMatchingParameters(java.util.Map parameters,
                                       java.util.Map environment)

Tests if the specified parameters match the specified environment.

The following specified IdM Connection parameters must match the specified environment exactly, or this method will return false.

 IdM Connection Parameters           =>    LDAP Context Environment
 ==============================================================================
 Connection.Parameter.AUTHENTICATION =>    LdapContext.SECURITY_AUTHENTICATION
 Connection.Parameter.PROTOCOL       =>    LdapContext.SECURITY_PROTOCOL
 

If any of the IdM Connection parameters were not specified, they will not be matched against the specified environment, and assumed to be irrelevant.

Specifying a null value for any of the IdM Connection parameters will make sure the corresponding setting from the specified environment is unspecified.

Returns:

true if the parameterts match the environment, false otherwise

checkParameters

protected void checkParameters(java.util.Map parameters,
                               java.util.Map environment)

Checks if parameters against environment for validity, called from actual operation methods.

canOpenLdapContext

public boolean canOpenLdapContext(java.util.Map parameters)
                           throws javax.naming.NamingException

This method determines if the LDAP Context can be opened using the specified IdM Connection parameters.

The following specified IdM Connection parameters must match the initial LDAP environment exactly, or the method will return false.

 IdM Connection Parameters           =>    LDAP Context Environment
 ==============================================================================
 Connection.Parameter.AUTHENTICATION =>    LdapContext.SECURITY_AUTHENTICATION
 Connection.Parameter.PROTOCOL       =>    LdapContext.SECURITY_PROTOCOL
 

If any of the IdM Connection parameters were not specified, they will not be matched against the initial LDAP environment, and assumed to be irrelevant.

Specifying a null value for any of the IdM Connection parameters will make sure the corresponding setting from the initial LDAP environment is unspecified.

Specified by:

canOpenLdapContext in interface LdapContextDelegate

Returns:

true if the ldap context can be opened, false otherwise

Throws:

javax.naming.NamingException

openLdapContext

public javax.naming.ldap.LdapContext openLdapContext(java.util.Map parameters,
                                                     int failSafeLevel)
                                              throws javax.naming.NamingException

This method opens a new LDAP context.

The following specified IdM Connection parameters must match the initial LDAP Context environment exactly, or a NamingException will be trown.

 IdM Connection Parameters           =>    LDAP Context Environment
 ==============================================================================
 Connection.Parameter.AUTHENTICATION =>    LdapContext.SECURITY_AUTHENTICATION
 Connection.Parameter.PROTOCOL       =>    LdapContext.SECURITY_PROTOCOL
 

If any of the IdM Connection parameters were not specified, they will not be matched against the initial LDAP Context environment, and assumed to be irrelevant.

Specifying a null value for any of the IdM Connection parameters will make sure the corresponding setting from the initial LDAP Context environment is unspecified.

The following specified IdM Connection parameters will be mapped to the new LDAP Context environment before opening a new context.

 IdM Connection Parameters           =>    LDAP Context Environment
 ==============================================================================
 Connection.Parameter.PRINCIPAL      =>    LdapContext.SECURITY_PRINCIPAL
 Connection.Parameter.CREDENTIALS    =>    LdapContext.SECURITY_CREDENTIALS
 

If any of the IdM Connection parameters were not specified, then the initial LDAP Context environment setting will be used. Otherwise the specified IdM Connection parameter will override the initial LDAP Context environment.

Specifying a null value for any of the IdM Connection parameters will remove the corresponding setting from the new LDAP Context environment.

Specified by:

openLdapContext in interface LdapContextDelegate

Returns:

the opened ldap context

Throws:

javax.naming.NamingException

canCloseLdapContext

public boolean canCloseLdapContext(javax.naming.ldap.LdapContext context,
                                   java.util.Map parameters)
                            throws javax.naming.NamingException

Description copied from interface: LdapContextDelegate

Returns true if the LDAP context can be closed.

Specified by:

canCloseLdapContext in interface LdapContextDelegate

Returns:

true if the ldap context can be closed, false otherwise

Throws:

javax.naming.NamingException

closeLdapContext

public void closeLdapContext(javax.naming.ldap.LdapContext context,
                             java.util.Map parameters,
                             int failSafeLevel)
                      throws javax.naming.NamingException

Description copied from interface: LdapContextDelegate

Closes the LDAP context.

Specified by:

closeLdapContext in interface LdapContextDelegate

Throws:

javax.naming.NamingException

canProxyLdapContext

public boolean canProxyLdapContext(javax.naming.ldap.LdapContext context,
                                   java.util.Map parameters)
                            throws javax.naming.NamingException

This method determines if the LDAP Context can be proxied to match the specified IdM Connection parameters.

The following specified IdM Connection parameters are assumed unmodifiable by the act of proxying and must match the current LDAP Context environment exactly.

 IdM Connection Parameters           =>    LDAP Context Environment
 ==============================================================================
 Connection.Parameter.AUTHENTICATION =>    LdapContext.SECURITY_AUTHENTICATION
 Connection.Parameter.PROTOCOL       =>    LdapContext.SECURITY_PROTOCOL
 

If any of the IdM Connection parameters were not specified, they will not be matched against the current LDAP Context environment, and assumed to be irrelevant.

Specifying a null value for any of the IdM Connection parameters will make sure the corresponding setting from the current LDAP Context environment is unspecified.

If reproxying is false, and the LDAP context has already been proxyied, this mothod will return false.

If unproxying is false, and the Connection.Parameter.PRINCIPAL parameter is unspecified or its value matches the value of the LdapContext.SECURITY_PRINCIPAL parameter in the initial environment, this method will return false, thus not allowing proxying back to the initial identity. Otherwise it will return true.

Specified by:

canProxyLdapContext in interface LdapContextDelegate

Returns:

true if the ldap context can be proxied, false otherwise

Throws:

javax.naming.NamingException

proxyLdapContext

public void proxyLdapContext(javax.naming.ldap.LdapContext context,
                             java.util.Map parameters,
                             int failSafeLevel)
                      throws javax.naming.NamingException,
                             java.lang.UnsupportedOperationException

This method proxies the LDAP context.

The following specified IdM Connection parameters must match the current LDAP Context environment exactly, or a NamingException will be trown.

 IdM Connection Parameters           =>    LDAP Context Environment
 ==============================================================================
 Connection.Parameter.AUTHENTICATION =>    LdapContext.SECURITY_AUTHENTICATION
 Connection.Parameter.PROTOCOL       =>    LdapContext.SECURITY_PROTOCOL
 

If any of the IdM Connection parameters were not specified, they will not be matched against the current LDAP Context environment, and assumed to be irrelevant.

Specifying a null value for any of the IdM Connection parameters will make sure the corresponding setting from the current LDAP Context environment is unspecified.

The following specified IdM Connection Parameters will be mapped to the current LDAP Context environment before proxying a context.

 IdM Connection Parameters           =>    LDAP Context Environment
 ==============================================================================
 Connection.Parameter.PRINCIPAL      =>    LdapContext.SECURITY_PRINCIPAL
 Connection.Parameter.CREDENTIALS    =>    LdapContext.SECURITY_CREDENTIALS
 

If any of the IdM Connection parameters were not specified, then the initial LDAP Context environment setting will be used. Otherwise the specified IdM Connection parameter will override the initial LDAP Context environment.

Specifying a null value for any of the IdM Connection parameters will remove the corresponding setting from the current LDAP Context environment.

Specified by:

proxyLdapContext in interface LdapContextDelegate

Throws:

javax.naming.NamingException

java.lang.UnsupportedOperationException

isMatchingLdapContext

public boolean isMatchingLdapContext(javax.naming.ldap.LdapContext context,
                                     java.util.Map parameters)
                              throws javax.naming.NamingException

This method matches the LDAP Context environment against the specified IdM Connection parameters.

The following specified IdM Connection parameters must match the current LDAP Context environment exactly, or this methos will return false.

 IdM Connection Parameters           =>    LDAP Context Environment
 ==============================================================================
 Connection.Parameter.AUTHENTICATION =>    LdapContext.SECURITY_AUTHENTICATION
 Connection.Parameter.PROTOCOL       =>    LdapContext.SECURITY_PROTOCOL
 

If any of the IdM Connection parameters were not specified, they will not be matched against the current LDAP Context environment, and assumed to be irrelevant.

Specifying a null value for any of the IdM Connection parameters will make sure the corresponding setting from the current LDAP Context environment is unspecified.

The following specified IdM Connection parameters must match the current LDAP Context environment exactly, or this methos will return false.

 IdM Connection Parameters           =>    LDAP Context Environment
 ==============================================================================
 Connection.Parameter.PRINCIPAL      =>    LdapContext.SECURITY_PRINCIPAL
 Connection.Parameter.CREDENTIALS    =>    LdapContext.SECURITY_CREDENTIALS
 

If any of the IdM Connection parameters were not specified, then the initial LDAP Context environment setting will be matched against the current LDAP Context environment.

Specifying a null value for any of the IdM Connection parameters will make sure the corresponding setting from the current LDAP Context environment is unspecified.

Specified by:

isMatchingLdapContext in interface LdapContextDelegate

Returns:

true if the ldap context matches the parametes, false otherwise

Throws:

javax.naming.NamingException

isAlteredLdapContext

public boolean isAlteredLdapContext(javax.naming.ldap.LdapContext context,
                                    java.util.Map environment)
                             throws javax.naming.NamingException

Description copied from interface: LdapContextDelegate

Returns true if this LDAP context environment is altered with regards to the one passed in.

Specified by:

isAlteredLdapContext in interface LdapContextDelegate

Returns:

true if the ldap context has been altered, false otherwise

Throws:

javax.naming.NamingException

canValidateLdapContext

public boolean canValidateLdapContext(javax.naming.ldap.LdapContext context,
                                      java.util.Map parameters)
                               throws javax.naming.NamingException

Description copied from interface: LdapContextDelegate

Returns true if the LDAP context can be validated.

Specified by:

canValidateLdapContext in interface LdapContextDelegate

Returns:

true if the ldap context can be validated, false otherwise

Throws:

javax.naming.NamingException

validateLdapContext

public void validateLdapContext(javax.naming.ldap.LdapContext context,
                                java.util.Map parameters,
                                int failSafeLevel)
                         throws javax.naming.NamingException,
                                java.lang.UnsupportedOperationException

Description copied from interface: LdapContextDelegate

Validates the LDAP context.

If validation is not supported, throw UnsupportedOperationException.

Specified by:

validateLdapContext in interface LdapContextDelegate

Throws:

javax.naming.NamingException

java.lang.UnsupportedOperationException

cloneParameters

public java.util.Map cloneParameters(java.util.Map parameters)

Description copied from interface: LdapContextDelegate

This method colones parameters to be internalized by the connection.

This method returns a clone of original parameteres.

This method must hide all sensitive parameters.

Specified by:

cloneParameters in interface LdapContextDelegate

Returns:

cloned parameter map

cloneEnvironment

public java.util.Map cloneEnvironment(java.util.Map environment)

Clones environment and hides sensitive parameters.

Specified by:

cloneEnvironment in interface LdapContextDelegate

Returns:

cloned environment map

xprint

public void xprint(XmlPrintWriter out)

Prints LDAP context manager properties to the PrintWriter as an XML element.

Specified by:

xprint in interface XmlPrintable

Parameters:

out - PrintWriter for printing LDAP context manager propeties.

xprintBody

protected void xprintBody(XmlPrintWriter out)

This method prints the LDAP context manager XML tag body.

normalizeDn

protected java.lang.String normalizeDn(java.lang.String dn)

Normalizes distinsuished name for comparison purposes.

Returns:

normalized dn

cloneHashtable

protected static final java.util.Hashtable cloneHashtable(java.util.Map map)

This method clones a Map into a Hashtable. It always creates a new object.

I try to minimize use of Hashtables in my code for the following reasons:

They are synchronized, which means slow performance and potantial deadlocks.

They cannot contain null objects, which means they throw lots of exceptions.

If you don't deal with their exceptions, the code will break all the time.

If you deal with their exceptions, the code will be longer and unreadable.

I use HashMaps instead; this method converts them to Hashtables as needed.

Returns:

cloned map as a hashtable

isSpecified

protected static final boolean isSpecified(java.util.Map map,
                                           java.lang.String key)

Returns true if key is contained in the map, null pointer safe.

getValue

protected static final java.lang.Object getValue(java.util.Map map,
                                                 java.lang.String key)

Returns the value of the key from the map, null pointer safe.

equal

protected static final boolean equal(java.lang.Object object1,
                                     java.lang.Object object2)

Tests objects for equality, null pointer safe.

Returns:

true if objects are equal

Skip navigation links