Package edu.vt.middleware.ldap

Class AbstractLdap<T extends LdapConfig>

  • Type Parameters:
    T - type of LdapConfig
    All Implemented Interfaces:
    BaseLdap
    Direct Known Subclasses:
    Ldap, SearchDnResolver
    public abstract class AbstractLdap<T extends LdapConfig>
extends java.lang.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 18:41:34 +0200 (Sun, 27 Jun 2010) $
    Author:
    Middleware Services

    • Constructor Summary

      Constructors 
      Constructor Description
      AbstractLdap()  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      This will close the connection to the LDAP.
      protected boolean compare​(java.lang.String dn, java.lang.String filter, java.lang.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​(java.lang.String dn, javax.naming.directory.Attributes attrs)
      This will create the supplied dn in the LDAP namespace with the supplied attributes.
      protected void delete​(java.lang.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 javax.naming.directory.Attributes getAttributes​(java.lang.String dn, java.lang.String[] retAttrs, AttributeHandler... handler)
      This will return the matching attributes associated with the supplied dn.
      protected javax.naming.ldap.LdapContext getContext()
      This will return an initialized connection to the LDAP.
      protected java.util.Iterator<javax.naming.directory.SearchResult> getSchema​(java.lang.String dn)
      This will return the LDAP schema associated with the supplied dn.
      protected java.util.Iterator<javax.naming.NameClassPair> list​(java.lang.String dn)
      This will enumerate the names bounds to the specified context, along with the class names of objects bound to them.
      protected java.util.Iterator<javax.naming.Binding> listBindings​(java.lang.String dn)
      This will enumerate the names bounds to the specified context, along with the objects bound to them.
      protected void modifyAttributes​(java.lang.String dn, int modOp, javax.naming.directory.Attributes attrs)
      This will modify the supplied attributes for the supplied value given by the modification operation.
      protected void modifyAttributes​(java.lang.String dn, javax.naming.directory.ModificationItem[] mods)
      This will modify the supplied dn using the supplied modifications.
      protected void operationRetry​(javax.naming.ldap.LdapContext ctx, javax.naming.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 java.util.Iterator<javax.naming.directory.SearchResult> pagedSearch​(java.lang.String dn, java.lang.String filter, java.lang.Object[] filterArgs, javax.naming.directory.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​(java.lang.String oldDn, java.lang.String newDn)
      This will rename the supplied dn in the LDAP namespace.
      protected java.util.Iterator<javax.naming.directory.SearchResult> search​(java.lang.String dn, java.lang.String filter, java.lang.Object[] filterArgs, javax.naming.directory.SearchControls searchControls, SearchResultHandler... handler)
      This will query the LDAP with the supplied dn, filter, filter arguments, and search controls.
      protected java.util.Iterator<javax.naming.directory.SearchResult> searchAttributes​(java.lang.String dn, javax.naming.directory.Attributes matchAttrs, java.lang.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.
      java.lang.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<javax.naming.directory.SearchResult> SR_COPY_RESULT_HANDLER
        Default copy search result handler, used if none supplied.

      • NCP_COPY_RESULT_HANDLER

        protected static final CopyResultHandler<javax.naming.NameClassPair> NCP_COPY_RESULT_HANDLER
        Default copy name class pair handler.

      • BINDING_COPY_RESULT_HANDLER

        protected static final CopyResultHandler<javax.naming.Binding> BINDING_COPY_RESULT_HANDLER
        Default copy binding handler.

      • COPY_RESULT_HANDLER

        protected static final CopyResultHandler<java.lang.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​(java.lang.String dn,
                          java.lang.String filter,
                          java.lang.Object[] filterArgs)
                   throws javax.naming.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:
        javax.naming.NamingException - if the LDAP returns an error

      • search

        protected java.util.Iterator<javax.naming.directory.SearchResult> search​(java.lang.String dn,
                                                                         java.lang.String filter,
                                                                         java.lang.Object[] filterArgs,
                                                                         javax.naming.directory.SearchControls searchControls,
                                                                         SearchResultHandler... handler)
                                                                  throws javax.naming.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 javax.naming.DirContext#search( String, String, Object[], SearchControls).
        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:
        javax.naming.NamingException - if the LDAP returns an error

      • pagedSearch

        protected java.util.Iterator<javax.naming.directory.SearchResult> pagedSearch​(java.lang.String dn,
                                                                              java.lang.String filter,
                                                                              java.lang.Object[] filterArgs,
                                                                              javax.naming.directory.SearchControls searchControls,
                                                                              SearchResultHandler... handler)
                                                                       throws javax.naming.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:
        javax.naming.NamingException - if the LDAP returns an error

      • searchAttributes

        protected java.util.Iterator<javax.naming.directory.SearchResult> searchAttributes​(java.lang.String dn,
                                                                                   javax.naming.directory.Attributes matchAttrs,
                                                                                   java.lang.String[] retAttrs,
                                                                                   SearchResultHandler... handler)
                                                                            throws javax.naming.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 javax.naming.DirContext#search(String, Attributes, String[]).
        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:
        javax.naming.NamingException - if the LDAP returns an error

      • list

        protected java.util.Iterator<javax.naming.NameClassPair> list​(java.lang.String dn)
                                                       throws javax.naming.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:
        javax.naming.NamingException - if the LDAP returns an error

      • listBindings

        protected java.util.Iterator<javax.naming.Binding> listBindings​(java.lang.String dn)
                                                         throws javax.naming.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:
        javax.naming.NamingException - if the LDAP returns an error

      • getAttributes

        protected javax.naming.directory.Attributes getAttributes​(java.lang.String dn,
                                                          java.lang.String[] retAttrs,
                                                          AttributeHandler... handler)
                                                   throws javax.naming.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 javax.naming.DirContext#getAttributes(String, String[]).
        Parameters:
        dn - String named object in the LDAP
        retAttrs - String[] attributes to return
        handler - AttributeHandler[] to post process results
        Returns:
        Attributes
        Throws:
        javax.naming.NamingException - if the LDAP returns an error

      • getSchema

        protected java.util.Iterator<javax.naming.directory.SearchResult> getSchema​(java.lang.String dn)
                                                                     throws javax.naming.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 javax.naming.DirContext#getSchema(String).
        Parameters:
        dn - String named object in the LDAP
        Returns:
        Iterator - LDAP search result
        Throws:
        javax.naming.NamingException - if the LDAP returns an error

      • modifyAttributes

        protected void modifyAttributes​(java.lang.String dn,
                                int modOp,
                                javax.naming.directory.Attributes attrs)
                         throws javax.naming.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 javax.naming.DirContext#modifyAttributes( String, int, Attributes).
        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:
        javax.naming.NamingException - if the LDAP returns an error

      • modifyAttributes

        protected void modifyAttributes​(java.lang.String dn,
                                javax.naming.directory.ModificationItem[] mods)
                         throws javax.naming.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 javax.naming.DirContext#modifyAttributes(String, ModificationItem[]).
        Parameters:
        dn - String named object in the LDAP
        mods - ModificationItem[] modifications
        Throws:
        javax.naming.NamingException - if the LDAP returns an error

      • create

        protected void create​(java.lang.String dn,
                      javax.naming.directory.Attributes attrs)
               throws javax.naming.NamingException
        This will create the supplied dn in the LDAP namespace with the supplied attributes. See javax.naming.DirContext#createSubcontext(String, Attributes). 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:
        javax.naming.NamingException - if the LDAP returns an error

      • rename

        protected void rename​(java.lang.String oldDn,
                      java.lang.String newDn)
               throws javax.naming.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:
        javax.naming.NamingException - if the LDAP returns an error

      • delete

        protected void delete​(java.lang.String dn)
               throws javax.naming.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:
        javax.naming.NamingException - if the LDAP returns an error

      • connect

        public boolean connect()
                throws javax.naming.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:
        javax.naming.NamingException - if the LDAP cannot be reached

      • reconnect

        public boolean reconnect()
                  throws javax.naming.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:
        javax.naming.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 javax.naming.ldap.LdapContext getContext()
                                            throws javax.naming.NamingException
        This will return an initialized connection to the LDAP.
        Returns:
        LdapContext
        Throws:
        javax.naming.NamingException - if the LDAP returns an error

      • operationRetry

        protected void operationRetry​(javax.naming.ldap.LdapContext ctx,
                              javax.naming.NamingException e,
                              int count)
                       throws javax.naming.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:
        javax.naming.NamingException - if the operation won't be retried

      • toString

        public java.lang.String toString()
        Provides a descriptive string representation of this instance.
        Overrides:
        toString in class java.lang.Object
        Returns:
        String of the form $Classname@hashCode::config=$config.

      • finalize

        protected void finalize()
                 throws java.lang.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 java.lang.Object
        Throws:
        java.lang.Throwable - if an exception is thrown by this method