ca.tnt.ldaputils
Class LdapManager

java.lang.Object
  ca.tnt.ldaputils.LdapManager

public class LdapManager
extends Object

Encapsulates LDAP access in to an easy to use factory object. The purpose is to provide a method of access LDAP that is similar to JPA, but specifically customized for LDAP purposes. JPA's annotations did not seem to fit the bill enough to warrant creating a JPA provider for LDAP.

The main reason for starting this project is that I have found Sun JNDI interfaces too cumbersome to use for my simple purposes.

Created : Feb 28, 2006 7:43:12 PM MST

Author:

Trenton D. Adams

Field Summary

static int	NO_ORDER Return search results in no particular order.
static int	SEARCH_ORDER Return search results in the order they were found.
static int	SORTED_ORDER Return search result in alphanumeric order, sorting by the keyAttribute.

Constructor Summary

LdapManager()
Initializes internal data store parameters.

LdapManager(String sLDAPHost, String sLDAPPort, String sLDAPManagerDN, String sLDAPManagerPW)
Initialize LdapManager instance with the host, port, auth dn, and auth password set.

Method Summary

void	bind(Object ldapEntry) Binds the LdapEntity annotated object to ldap, with all of it's attributes.
Object	find(Class annotatedClass, LdapName dn) Retrieves the exact LdapEntity POJO you specify, using the dn passed in.
Map	find(LdapName baseDN, String searchFilter, String keyAttribute, String[] attributes, Class ldapEntryClass, int sorted, int searchScope) Do a search and return a Map of the entries.
Attributes	getAttributes(LdapName dn, String[] attributes)
Object[]	getAttributes(String baseDN, String searchFilter, String[] attributes) Generic method for retrieving entry attributes from the LDAP store.
DirContext	getConnection()
static DirContext	getConnection(boolean isPooled, int timeout, String sLDAPURL, String sLDAPManagerDN, String sLDAPManagerPW) Gets an LDAP directory context.
static String	getNamingExceptionMessage(NamingException namingException) Returns an appropriate message for the exception.
static void	logNamingException(NamingException namingException)
static void	main(String[] args) Hopefully provides an example of how to use all the basic features of the LDAP objects framework.
static void	releaseConnection(DirContext conn) Releases an LDAP directory context.
void	unbind(ILdapEntry ldapEntry)
void	unbind(LdapName dn)

Methods inherited from class java.lang.Object

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

Field Detail

NO_ORDER

public static final int NO_ORDER

Return search results in no particular order. i.e. the are stored in a non sorted Map. Probably a Hashtable.

See Also:

Constant Field Values

SEARCH_ORDER

public static final int SEARCH_ORDER

Return search results in the order they were found.

See Also:

Constant Field Values

SORTED_ORDER

public static final int SORTED_ORDER

Return search result in alphanumeric order, sorting by the keyAttribute.

See Also:

Constant Field Values

Constructor Detail

LdapManager

public LdapManager()

Initializes internal data store parameters. Namely loads the ldap.properties file from the classpath.

LdapManager

public LdapManager(String sLDAPHost,
                   String sLDAPPort,
                   String sLDAPManagerDN,
                   String sLDAPManagerPW)

Initialize LdapManager instance with the host, port, auth dn, and auth password set.

Parameters:

sLDAPHost - the ldap host

sLDAPPort - the ldap port

sLDAPManagerDN - the fully qualified DN of the ldap manager account, or one of sufficient privileges to carry out the required operations

sLDAPManagerPW - the password of the sLDAPManagerDN account.

Method Detail

find

public Map find(LdapName baseDN,
                String searchFilter,
                String keyAttribute,
                String[] attributes,
                Class ldapEntryClass,
                int sorted,
                int searchScope)

Do a search and return a Map of the entries. They key is the value of the keyAttribute that you passed in. So, if you wanted "cn" to be the key, you would pass "cn" in for the keyAttribute. Then the value of "cn", for a particular entry, would be the key you use to find that entry. It is assumed that the key can be typecast to a java.lang.String.

It is your responsibility to make sure that the keyAttribute exists in the attributes parameter, and that any results returned will also have that attribute set. So do not set keyAttribute to an attribute that is not required by LDAP, unless you know that it will always have values for it due to your business practices. For instance, the mail attribute is not required on every person entry, but the uid attribute is. So uid would be a good keyAttribute, as we know that it MUST exist in LDAP.

In addition, the caller is required to be very careful that they do not search subtrees that could potentially return the same "keyAttribute" value. If this happened, then only the last entry found would be in the hashtable. for instance, you may have a uid=trenta,ou=People,dc=domain,dc=ca entry as well as a uid=trenta,ou=Staff,ou=People,dc=domain,dc=ca entry. If your keyAttribute is uid, then only the last item found will be in the returned Map. If you do not want to search subtree, just specify SearchControls.ONELEVEL_SCOPE as the "searchScope" parameter.

Parameters:

baseDN - the base DN to search on

searchFilter - the ldap search filter to use for ldap entry retreival.

keyAttribute - the attribute that will be the key for the getSortedAttributes() method that returns a SortedMap

attributes - the array of attribute names to retrieve. If you want ALL attributes to be loaded for a particular LDAPObject, then pass in a null value for this parameter

ldapEntryClass - the clas of the object that is annotated

sorted - One of NO_ORDER, SEARCH_ORDER, SORTED_ORDER

searchScope - One of the scope values in SearchControls

Returns:

a map of LDAPObjects with the keys being the keyAttribute value

Throws:

LdapNamingException - if any naming problems occur

See Also:

NO_ORDER, SEARCH_ORDER, SORTED_ORDER

find

public Object find(Class annotatedClass,
                   LdapName dn)

Retrieves the exact LdapEntity POJO you specify, using the dn passed in. You must pass in a fully qualified DN.

Parameters:

annotatedClass - the class that has been annotated with ldaputil annotations

dn - the LDAP Distinquished Name.

Returns:

the LdapEntity annotated POJO that you specified in annotatedClass, or null if it was not found

Throws:

LdapNamingException - if any ldap naming errors occur.

IllegalArgumentException - if the annotatedClass is not correctly annotated in some way

getAttributes

public Object[] getAttributes(String baseDN,
                              String searchFilter,
                              String[] attributes)

Generic method for retrieving entry attributes from the LDAP store. There is no need to log any NamingExceptions that have been thrown from this method. They will have already been logged. This method returns an array of non-null "Attributes" objects. Each array index corresponds to a 'DN' entry found in LDAP by the searchFilter.

Parameters:

baseDN - the DN given.

searchFilter - the ldap search filter to use for ldap entry retrieval.

attributes - array with the attribute names to grab

Returns:

array of "Attributes"

Throws:

LdapNamingException - if an ldap error occurs

getAttributes

public Attributes getAttributes(LdapName dn,
                                String[] attributes)

getConnection

public static DirContext getConnection(boolean isPooled,
                                       int timeout,
                                       String sLDAPURL,
                                       String sLDAPManagerDN,
                                       String sLDAPManagerPW)
                                throws NamingException

Gets an LDAP directory context.

REQUIRED_FEATURE authentication mechanism (issue-14)

Parameters:

isPooled - turn pooling on?

timeout - the connection timeout value

sLDAPURL - the ldap url

sLDAPManagerDN - the manager dn

sLDAPManagerPW - @return an LDAP directory context object

Returns:

the new DirContext

Throws:

NamingException - if a JNDI error occurs.

getConnection

public DirContext getConnection()
                         throws NamingException

Throws:

NamingException

releaseConnection

public static void releaseConnection(DirContext conn)

Releases an LDAP directory context.

Parameters:

conn - LDAP directory context object

logNamingException

public static void logNamingException(NamingException namingException)

getNamingExceptionMessage

public static String getNamingExceptionMessage(NamingException namingException)

Returns an appropriate message for the exception.

Parameters:

namingException - the exception

Returns:

the message to log

main

public static void main(String[] args)

Hopefully provides an example of how to use all the basic features of the LDAP objects framework.

Parameters:

args - the arguments to pass in.

bind

public void bind(Object ldapEntry)

Binds the LdapEntity annotated object to ldap, with all of it's attributes.

CRITICAL updating annotation processor (issue-5)

Parameters:

ldapEntry - LdapEntity annotated object

Throws:

UnsupportedOperationException - if there is some error in the code that uses the recursive binding functionality. This shouldn't happen, if it does, it's a bug, and needs to be reported.

unbind

public void unbind(LdapName dn)

unbind

public void unbind(ILdapEntry ldapEntry)