edu.vt.middleware.ldap
Class AbstractLdap<T extends LdapConfig>

java.lang.Object
  edu.vt.middleware.ldap.AbstractLdap<T>

Type Parameters:

T - type of LdapConfig

All Implemented Interfaces:

BaseLdap

Direct Known Subclasses:

Ldap, SearchDnResolver

public abstract class AbstractLdap<T extends LdapConfig>
extends Object
implements BaseLdap

AbstractLdap contains the functions for basic interaction with a LDAP. Methods are provided for connecting, binding, querying and updating.

Version:

$Revision: 1440 $ $Date: 2010-06-27 12:41:34 -0400 (Sun, 27 Jun 2010) $

Author:

Middleware Services

Field Summary

protected static CopyResultHandler<Binding>	BINDING_COPY_RESULT_HANDLER Default copy binding handler.
protected T	config LDAP configuration environment.
protected ConnectionHandler	connectionHandler LDAP connection handler.
protected static CopyResultHandler<Object>	COPY_RESULT_HANDLER Default copy result handler.
protected org.apache.commons.logging.Log	logger Log for this class.
protected static CopyResultHandler<NameClassPair>	NCP_COPY_RESULT_HANDLER Default copy name class pair handler.
protected static CopyResultHandler<SearchResult>	SR_COPY_RESULT_HANDLER Default copy search result handler, used if none supplied.

Constructor Summary

AbstractLdap()

Method Summary

void	close() This will close the connection to the LDAP.
protected boolean	compare(String dn, String filter, Object[] filterArgs) This will perform an LDAP compare operation with the supplied filter and dn.
boolean	connect() This will establish a connection if one does not already exist by binding to the LDAP using parameters given by LdapConfig.getBindDn() and LdapConfig.getBindCredential().
protected void	create(String dn, Attributes attrs) This will create the supplied dn in the LDAP namespace with the supplied attributes.
protected void	delete(String dn) This will delete the supplied dn from the LDAP namespace.
protected void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
protected Attributes	getAttributes(String dn, String[] retAttrs, AttributeHandler... handler) This will return the matching attributes associated with the supplied dn.
protected LdapContext	getContext() This will return an initialized connection to the LDAP.
protected Iterator<SearchResult>	getSchema(String dn) This will return the LDAP schema associated with the supplied dn.
protected Iterator<NameClassPair>	list(String dn) This will enumerate the names bounds to the specified context, along with the class names of objects bound to them.
protected Iterator<Binding>	listBindings(String dn) This will enumerate the names bounds to the specified context, along with the objects bound to them.
protected void	modifyAttributes(String dn, int modOp, Attributes attrs) This will modify the supplied attributes for the supplied value given by the modification operation.
protected void	modifyAttributes(String dn, ModificationItem[] mods) This will modify the supplied dn using the supplied modifications.
protected void	operationRetry(LdapContext ctx, NamingException e, int count) Confirms whether the supplied exception matches an exception from LdapConfig.getOperationRetryExceptions() and the supplied count is less than LdapConfig.getOperationRetry().
protected Iterator<SearchResult>	pagedSearch(String dn, String filter, Object[] filterArgs, SearchControls searchControls, SearchResultHandler... handler) This will query the LDAP with the supplied dn, filter, filter arguments, and search controls.
boolean	reconnect() This will close the current connection to the LDAP and establish a new connection to the LDAP using connect().
protected void	rename(String oldDn, String newDn) This will rename the supplied dn in the LDAP namespace.
protected Iterator<SearchResult>	search(String dn, String filter, Object[] filterArgs, SearchControls searchControls, SearchResultHandler... handler) This will query the LDAP with the supplied dn, filter, filter arguments, and search controls.
protected Iterator<SearchResult>	searchAttributes(String dn, Attributes matchAttrs, String[] retAttrs, SearchResultHandler... handler) This will query the LDAP for the supplied dn, matching attributes and return attributes.
protected void	setLdapConfig(T ldapConfig) This will set the config parameters of this Ldap.
String	toString() Provides a descriptive string representation of this instance.

Methods inherited from class java.lang.Object

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

Field Detail

SR_COPY_RESULT_HANDLER

protected static final CopyResultHandler<SearchResult> SR_COPY_RESULT_HANDLER

Default copy search result handler, used if none supplied.

NCP_COPY_RESULT_HANDLER

protected static final CopyResultHandler<NameClassPair> NCP_COPY_RESULT_HANDLER

Default copy name class pair handler.

BINDING_COPY_RESULT_HANDLER

protected static final CopyResultHandler<Binding> BINDING_COPY_RESULT_HANDLER

Default copy binding handler.

COPY_RESULT_HANDLER

protected static final CopyResultHandler<Object> COPY_RESULT_HANDLER

Default copy result handler.

logger

protected final org.apache.commons.logging.Log logger

Log for this class.

connectionHandler

protected ConnectionHandler connectionHandler

LDAP connection handler.

config

protected T extends LdapConfig config

LDAP configuration environment.

Constructor Detail

AbstractLdap

public AbstractLdap()

Method Detail

setLdapConfig

protected void setLdapConfig(T ldapConfig)

This will set the config parameters of this Ldap.

Parameters:

ldapConfig - LdapConfig

compare

protected boolean compare(String dn,
                          String filter,
                          Object[] filterArgs)
                   throws NamingException

This will perform an LDAP compare operation with the supplied filter and dn. Note that to perform a real LDAP compare operation, your filter must be of the form '(name=value)'. Any other filter expression will result in a regular object level search operation. In either case the desired result is achieved, but the underlying LDAP invocation is different.

Parameters:

dn - String name to compare

filter - String expression to use for compare

filterArgs - Object[] to substitute for variables in the filter

Returns:

boolean - result of compare operation

Throws:

NamingException - if the LDAP returns an error

search

protected Iterator<SearchResult> search(String dn,
                                        String filter,
                                        Object[] filterArgs,
                                        SearchControls searchControls,
                                        SearchResultHandler... handler)
                                 throws NamingException

This will query the LDAP with the supplied dn, filter, filter arguments, and search controls. This method will perform a search whose scope is defined in the search controls. The resulting Iterator is a deep copy of the original search results. If filterArgs is null, then no variable substitution will occur. See DirContext.

Parameters:

dn - String name to begin search at

filter - String expression to use for the search

filterArgs - Object[] to substitute for variables in the filter

searchControls - SearchControls to perform search with

handler - SearchResultHandler[] to post process results

Returns:

Iterator - of LDAP search results

Throws:

NamingException - if the LDAP returns an error

pagedSearch

protected Iterator<SearchResult> pagedSearch(String dn,
                                             String filter,
                                             Object[] filterArgs,
                                             SearchControls searchControls,
                                             SearchResultHandler... handler)
                                      throws NamingException

This will query the LDAP with the supplied dn, filter, filter arguments, and search controls. See search(String, String, Object[], SearchControls, SearchResultHandler...). The PagedResultsControl is used in conjunction with LdapConfig.getPagedResultsSize() to produce the results.

Parameters:

dn - String name to begin search at

filter - String expression to use for the search

filterArgs - Object[] to substitute for variables in the filter

searchControls - SearchControls to perform search with

handler - SearchResultHandler[] to post process results

Returns:

Iterator - of LDAP search results

Throws:

NamingException - if the LDAP returns an error

searchAttributes

protected Iterator<SearchResult> searchAttributes(String dn,
                                                  Attributes matchAttrs,
                                                  String[] retAttrs,
                                                  SearchResultHandler... handler)
                                           throws NamingException

This will query the LDAP for the supplied dn, matching attributes and return attributes. This method will always perform a one level search. The resulting Iterator is a deep copy of the original search results. If matchAttrs is empty or null then all objects in the target context are returned. If retAttrs is null then all attributes will be returned. If retAttrs is an empty array then no attributes will be returned. See DirContext.

Parameters:

dn - String name to search in

matchAttrs - Attributes attributes to match

retAttrs - String[] attributes to return

handler - SearchResultHandler[] to post process results

Returns:

Iterator - of LDAP search results

Throws:

NamingException - if the LDAP returns an error

list

protected Iterator<NameClassPair> list(String dn)
                                throws NamingException

This will enumerate the names bounds to the specified context, along with the class names of objects bound to them. The resulting Iterator is a deep copy of the original search results. See Context.list(String).

Parameters:

dn - String LDAP context to list

Returns:

Iterator - LDAP search result

Throws:

NamingException - if the LDAP returns an error

listBindings

protected Iterator<Binding> listBindings(String dn)
                                  throws NamingException

This will enumerate the names bounds to the specified context, along with the objects bound to them. The resulting Iterator is a deep copy of the original search results. See Context.listBindings(String).

Parameters:

dn - String LDAP context to list

Returns:

Iterator - LDAP search result

Throws:

NamingException - if the LDAP returns an error

getAttributes

protected Attributes getAttributes(String dn,
                                   String[] retAttrs,
                                   AttributeHandler... handler)
                            throws NamingException

This will return the matching attributes associated with the supplied dn. If retAttrs is null then all attributes will be returned. If retAttrs is an empty array then no attributes will be returned. See DirContext.

Parameters:

dn - String named object in the LDAP

retAttrs - String[] attributes to return

handler - AttributeHandler[] to post process results

Returns:

Attributes

Throws:

NamingException - if the LDAP returns an error

getSchema

protected Iterator<SearchResult> getSchema(String dn)
                                    throws NamingException

This will return the LDAP schema associated with the supplied dn. The resulting Iterator is a deep copy of the original search results. See DirContext.

Parameters:

dn - String named object in the LDAP

Returns:

Iterator - LDAP search result

Throws:

NamingException - if the LDAP returns an error

modifyAttributes

protected void modifyAttributes(String dn,
                                int modOp,
                                Attributes attrs)
                         throws NamingException

This will modify the supplied attributes for the supplied value given by the modification operation. modOp must be one of: ADD_ATTRIBUTE, REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE. The order of the modifications is not specified. Where possible, the modifications are performed atomically. See DirContext.

Parameters:

dn - String named object in the LDAP

modOp - int modification operation

attrs - Attributes attributes to be used for the operation, may be null

Throws:

NamingException - if the LDAP returns an error

modifyAttributes

protected void modifyAttributes(String dn,
                                ModificationItem[] mods)
                         throws NamingException

This will modify the supplied dn using the supplied modifications. The modifications are performed in the order specified. Each modification specifies a modification operation code and an attribute on which to operate. Where possible, the modifications are performed atomically. See DirContext.

Parameters:

dn - String named object in the LDAP

mods - ModificationItem[] modifications

Throws:

NamingException - if the LDAP returns an error

create

protected void create(String dn,
                      Attributes attrs)
               throws NamingException

This will create the supplied dn in the LDAP namespace with the supplied attributes. See DirContext. Note that the context created by this operation is immediately closed.

Parameters:

dn - String named object in the LDAP

attrs - Attributes attributes to be added to this entry

Throws:

NamingException - if the LDAP returns an error

rename

protected void rename(String oldDn,
                      String newDn)
               throws NamingException

This will rename the supplied dn in the LDAP namespace. See Context.rename(String, String).

Parameters:

oldDn - String object to rename

newDn - String new name

Throws:

NamingException - if the LDAP returns an error

delete

protected void delete(String dn)
               throws NamingException

This will delete the supplied dn from the LDAP namespace. Note that this method does not throw NameNotFoundException if the supplied dn does not exist. See Context.destroySubcontext(String).

Parameters:

dn - String named object in the LDAP

Throws:

NamingException - if the LDAP returns an error

connect

public boolean connect()
                throws NamingException

This will establish a connection if one does not already exist by binding to the LDAP using parameters given by LdapConfig.getBindDn() and LdapConfig.getBindCredential(). If these parameters have not been set then an anonymous bind will be attempted. This connection must be closed using close(). Any method which requires an LDAP connection will call this method independently. This method should only be used if you need to verify that you can connect to the LDAP.

Specified by:

connect in interface BaseLdap

Returns:

boolean - whether the connection was successful

Throws:

NamingException - if the LDAP cannot be reached

reconnect

public boolean reconnect()
                  throws NamingException

This will close the current connection to the LDAP and establish a new connection to the LDAP using connect().

Specified by:

reconnect in interface BaseLdap

Returns:

boolean - whether the connection was successful

Throws:

NamingException - if the LDAP cannot be reached

close

public void close()

This will close the connection to the LDAP.

Specified by:

close in interface BaseLdap

getContext

protected LdapContext getContext()
                          throws NamingException

This will return an initialized connection to the LDAP.

Returns:

LdapContext

Throws:

NamingException - if the LDAP returns an error

operationRetry

protected void operationRetry(LdapContext ctx,
                              NamingException e,
                              int count)
                       throws NamingException

Confirms whether the supplied exception matches an exception from LdapConfig.getOperationRetryExceptions() and the supplied count is less than LdapConfig.getOperationRetry(). LdapConfig.getOperationRetryWait() is used in conjunction with LdapConfig.getOperationRetryBackoff() to delay retries. Calls close() if no exception is thrown, which allows the client to reconnect when the operation is performed again.

Parameters:

ctx - LdapContext that performed the operation

e - NamingException that was thrown

count - int operation attempts

Throws:

NamingException - if the operation won't be retried

toString

public String toString()

Provides a descriptive string representation of this instance.

Overrides:

toString in class Object

Returns:

String of the form $Classname@hashCode::config=$config.

finalize

protected void finalize()
                 throws Throwable

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Overrides:

finalize in class Object

Throws:

Throwable - if an exception is thrown by this method