com.ibm.di.connector
Class LDAPConnector

java.lang.Object
  extended by com.ibm.di.connector.Connector
      extended by com.ibm.di.connector.LDAPConnector
All Implemented Interfaces:
ConnectorInterface, VersionInfoInterface
Direct Known Subclasses:
ADChangelogConnector, ADChangelogConnectorv2, ChangelogConnector, LDAPGroupConnector

public class LDAPConnector
extends Connector
implements ConnectorInterface

The LDAP connector provides full access to LDAP based directories. It allows operations on user entries and schema.


Field Summary
 
Fields inherited from class com.ibm.di.connector.Connector
ALL_MODES, myLog, PROPERTY_MESSAGE, PROPERTY_READER, PROPERTY_WRITER
 
Constructor Summary
LDAPConnector()
          Constructor for the LDAPConnector object
 
Method Summary
 void addAttributeValue(String moddn, String modattr, String modval)
          Adds a given value to an attribute.
 BasicAttributes at2entry(Entry entry, boolean removeEmptyAttrs)
          Internal method used to convert an Entry into BasicAttributes that can be sent to the LDAP Server
 void callErrorHookOnAttributeInUseException(boolean errorHook)
          Sets the value for invoking error hook on attribute in use exception
 boolean compare(String compdn, String attname, String attvalue)
          compare: performs an ldapcompare operation for the given parameters
 void deleteEntry(Entry entry, SearchCriteria search)
          Delete an entry in the LDAP Server.
 Entry entry2at(SearchResult sr)
          Internal method used to convert a SearchResult from the LDAP Server to an Entry.
 Entry findEntry(SearchCriteria search)
          Find an entry matching a SearchCriteria.
 boolean flagSet(int flag)
          Utility method to see if a flag is set
 String getAttributeSyntax(DirContext schema, String attributeName)
          Gets an Attribute Syntax from the LDAP Server
 boolean getCallErrorHook()
          Returns true if Error hooks should be called on AttributeInUseException
 Entry getCurrentEntry()
          Gets the current Entry.
 InitialLdapContext getLdapContext()
          Returns the InitialLdapContext (Connection to the LDAP Server)
 Entry getNextEntry()
          Get the next entry that was retrieved by selectEntries().
 Vector<Object> getServerControls()
          Get the supported server Controls from the LDAP Server
 Entry getServerInfo()
          Gets the serverInfo from the LDAP Server
 String getVersion()
          Version information.
 void initialize(Object o)
          Initialize the Connector, connect to the LDAP Server
 boolean isDeltaSupported()
          This connector is able to perform delta updates
 boolean isExceptionFatal(Exception e)
          Utility method, that checks if an Exception thrown by underlying libraries is fatal
 boolean isServerAdminControl()
          Returns true if Server Adming control has been set
 String mapAttributeSyntax(String oid)
          Utility method used for parsing attribute syntax
 void modEntry(Entry entry, SearchCriteria search)
          Modify an Object in the LDAP Server.
 void modEntry(Entry entry, SearchCriteria search, Entry old)
          Modify an Object in the LDAP Server.
 void moveEntry(String p1, String p2)
          If the LDAP Server does not support renaming, this method can be used to delete an object and recreating it with another name
 void putEntry(Entry entry)
          Adds a new entry to the data source.
 Vector<Object> queryNamingContexts()
          Query the LDAP Server for naming contexts
 Vector<Object> queryObjectClassAttributes(String objectClass)
          Look up an objectclass in the LDAP Server.
 Object querySchema(Object source)
          Query the schema of the LDAP server.
 void rebind(String dn, String password)
          Attempts to reauthenticate using the currently open connection.
 void rebind(String dn, String password, String authMethod)
          Attempts to reauthenticate using the currently open connection.
 void removeAllAttributeValues(String moddn, String modattr)
          removeAllAttributeValues: removes all values for a given attribute
 void removeAttributeValue(String moddn, String modattr, String modval)
          removeAttributeValue: removes a given attribute value from an entry
 void replaceAttributeValue(String moddn, String modattr, String modval)
          replaceAttributeValue: replaces a given attribute with a certain value
 void selectEntries()
          Prepare the Connector for sequential read.
 Attribute setADPassword(Object password)
          setADPassword - Returns an Attribute (JNDI) containing the UNICODE version of a password for ActiveDirectory.
 void setServerAdminControl(boolean valueOfserverAdminControl)
          Sets the server admin control to either true or false.
 void setsubtreeDeleteSupported(boolean subtreeDeleteSupported)
          Allows deleting subtrees.
 void showServerInfo()
          Logs server information, supported controls and naming contexts
 boolean supportsControl(String oid)
          Check if the LDAP Server supports a Control
 boolean supportsExtension(String oid)
          Check if the LDAP Server supports an Extension
 boolean supportsPagedResults()
          Check if the LDAP Server supports paged results
 boolean supportsPersistantSearch()
          Check if the LDAP Server supports Persistant Search
 boolean supportsSorting()
          Check if the LDAP Server supports sorting
 boolean supportsVirtualListView()
          Check if the LDAP Server supports virtual list view
 void terminate()
          Close the connection to the LDAP server
 
Methods inherited from class com.ibm.di.connector.Connector
addFindEntry, allModes, clearFindEntries, debug, debugMode, findEntry, getBoolean, getClassInstance, getConfiguration, getContext, getFindEntryCount, getFirstFindEntry, getLog, getMaxDuplicateEntries, getModes, getModes, getName, getNextClient, getNextFindEntry, getParam, getParser, getProperty, getPushbackEntry, getRawConnectorConfiguration, getRSInterface, getUI, hasConfigValue, hasParser, initParser, isIOException, logError, logmsg, pushback, queryOperations, queryReply, queryTables, reconnect, reconnect, registerScriptBeans, replyEntry, setConfiguration, setContext, setCurrent, setDebugMode, setLog, setMaxDuplicateEntries, setModes, setModes, setName, setParam, setParser, setProperty, setRSInterface, terminateServer
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.ibm.di.connector.ConnectorInterface
getConfiguration, getContext, getFindEntryCount, getFirstFindEntry, getMaxDuplicateEntries, getName, getNextClient, getNextFindEntry, getParam, getPushbackEntry, getRawConnectorConfiguration, isIOException, pushback, queryOperations, queryReply, reconnect, registerScriptBeans, replyEntry, setConfiguration, setContext, setCurrent, setLog, setMaxDuplicateEntries, setName, setParam, setRSInterface, terminateServer
 

Constructor Detail

LDAPConnector

public LDAPConnector()
Constructor for the LDAPConnector object

Method Detail

terminate

public void terminate()
Close the connection to the LDAP server

Specified by:
terminate in interface ConnectorInterface
Overrides:
terminate in class Connector

getLdapContext

public InitialLdapContext getLdapContext()
Returns the InitialLdapContext (Connection to the LDAP Server)

Returns:
The connection to the LDAP Server

isServerAdminControl

public boolean isServerAdminControl()
Returns true if Server Adming control has been set

Returns:
Boolean

setServerAdminControl

public void setServerAdminControl(boolean valueOfserverAdminControl)
Sets the server admin control to either true or false.

Parameters:
serverAdminControl -

initialize

public void initialize(Object o)
                throws Exception
Initialize the Connector, connect to the LDAP Server

Specified by:
initialize in interface ConnectorInterface
Overrides:
initialize in class Connector
Parameters:
o - An Object sent to the initialize method, ignored.
Throws:
Exception - Any Exception by the underlying methods to connect to the LDAP Server

selectEntries

public void selectEntries()
                   throws Exception
Prepare the Connector for sequential read. Begin retrieving records matching the Search Base

Specified by:
selectEntries in interface ConnectorInterface
Overrides:
selectEntries in class Connector
Throws:
Exception - Any Exception by the underlying library

getNextEntry

public Entry getNextEntry()
                   throws Exception
Get the next entry that was retrieved by selectEntries(). The Entry returned is populated with attributes and values from the next entry in the input set. The $dn Attribute of the returned Entry is the distinguished name. If we are using paged-find, possibly retrieve more results.

Specified by:
getNextEntry in interface ConnectorInterface
Overrides:
getNextEntry in class Connector
Returns:
The next Entry populated with values, or null if nore more Entries
Throws:
Exception - Any Exception thrown by the underlying libraries
See Also:
ConnectorInterface.selectEntries()

getCurrentEntry

public Entry getCurrentEntry()
Gets the current Entry. This is the last Entry returned by getNextEntry() )

Returns:
The current Entry

putEntry

public void putEntry(Entry entry)
              throws Exception
Adds a new entry to the data source. The entry parameter must have a $dn Attribute, specifying the distinguished name.

Specified by:
putEntry in interface ConnectorInterface
Overrides:
putEntry in class Connector
Parameters:
entry - An Entry populated with values that are to be sent to the LDAP server.
Throws:
Exception - If there is no distinguished name

modEntry

public void modEntry(Entry entry,
                     SearchCriteria search)
              throws Exception
Modify an Object in the LDAP Server. This call is equivalent to modEntry(entry, search, findEntry(search))

Specified by:
modEntry in interface ConnectorInterface
Overrides:
modEntry in class Connector
Parameters:
entry - An Entry populated with the values to modify
search - The SearchCriteria
Throws:
Exception - if an error occurs.
See Also:
modEntry(Entry, SearchCriteria, Entry)

modEntry

public void modEntry(Entry entry,
                     SearchCriteria search,
                     Entry old)
              throws Exception
Modify an Object in the LDAP Server. The supplied entry should contain a $dn Attribute with the distinguished name. If it does not, then either the SearchCriteria must be $dn equals some value, or the old Entry must contain a $dn Attribute. If the $dn Attribute in entry and old are different, we will try to rename the object in the LDAP Server. The easy way to use this method is to populate entry with the values you want to modify, and in particular supply a distinguished name. $dn Attribute, and let search and old be null.

Specified by:
modEntry in interface ConnectorInterface
Overrides:
modEntry in class Connector
Parameters:
entry - An Entry containing the new values to be set in the LDAP Server
search - Only used if there is no $dn Attribute in entry.
old - The old values, used to supply $dn if not present in Entry.
Throws:
Exception - If no distinguished name can be found

setsubtreeDeleteSupported

public void setsubtreeDeleteSupported(boolean subtreeDeleteSupported)
                               throws Exception
Allows deleting subtrees. If the parameter is true, any call to deleteEntry() will try to delete the entire specified subtree, rather than only a single element. If the parameter is false, no longer delete subtrees.

Parameters:
subtreeDeleteSupported - If true, delete subtrees.
Throws:
Exception

deleteEntry

public void deleteEntry(Entry entry,
                        SearchCriteria search)
                 throws Exception
Delete an entry in the LDAP Server. The distinguished name is provided by the $dn Attribute in the entry parameter. If not found there. the SearchCriteria. must be of the form $dn equals value.

Specified by:
deleteEntry in interface ConnectorInterface
Overrides:
deleteEntry in class Connector
Parameters:
entry - An Entry object containing the distinguished name of the entry to delete.
search - Used if the entry parameter is null, or does not contain a distinguished name.
Throws:
Exception - If no distinguished name can be found.

findEntry

public Entry findEntry(SearchCriteria search)
                throws Exception
Find an entry matching a SearchCriteria. Returns an entry if exactly one match is found. If more than one Entry is found, getFindEntryCount() will say how many matches were found.

Specified by:
findEntry in interface ConnectorInterface
Overrides:
findEntry in class Connector
Parameters:
search - The SearchCriteria containing the values to match.
Returns:
The entry that matches the SearchCriteria
Throws:
Exception - Any Exception thrown by the underlying libraries

isExceptionFatal

public boolean isExceptionFatal(Exception e)
Utility method, that checks if an Exception thrown by underlying libraries is fatal

Specified by:
isExceptionFatal in interface ConnectorInterface
Overrides:
isExceptionFatal in class Connector
Parameters:
e - The Exception
Returns:
true if this is a fatal Exception

entry2at

public Entry entry2at(SearchResult sr)
Internal method used to convert a SearchResult from the LDAP Server to an Entry.

Parameters:
sr - The SearchResult
Returns:
The sr parameter converted to an Entry.

at2entry

public BasicAttributes at2entry(Entry entry,
                                boolean removeEmptyAttrs)
                         throws Exception
Internal method used to convert an Entry into BasicAttributes that can be sent to the LDAP Server

Parameters:
entry - The Entry to convert to BasicAttributes
removeEmptyAttrs - If true, do not include empty Attributes in the BasicAttributes
Returns:
The Entry converted to BasicAttributes
Throws:
Exception - If the userPassword Attribute is multivalued, and the Auto Map AD Password parameter is set

moveEntry

public void moveEntry(String p1,
                      String p2)
               throws Exception
If the LDAP Server does not support renaming, this method can be used to delete an object and recreating it with another name

Parameters:
p1 - The old distinguished name
p2 - The new distinguished name
Throws:
Exception - If the old entry could not be deleted
Exception - If the old entry could be deleted, but the new entry could not be added

compare

public boolean compare(String compdn,
                       String attname,
                       String attvalue)
                throws Exception
compare: performs an ldapcompare operation for the given parameters

Parameters:
compdn - String representing the DN for which to do a compare
attname - String representing the name of the attribute to compare (left side of ldap filter)
attvalue - String representing the value of the attribute to compare (right side of ldap filter)
Returns:
boolean True if the compare evaluates as true, False otherwise
Throws:
Exception - when underlying compare funtion fails

addAttributeValue

public void addAttributeValue(String moddn,
                              String modattr,
                              String modval)
                       throws Exception
Adds a given value to an attribute.

Parameters:
moddn - String representing the DN to which to add the attribute value
modattr - String representing the name of the attribute to add a value to
modval - String representing the value of the attribute add
Throws:
Exception - when underlying modify operation fails

replaceAttributeValue

public void replaceAttributeValue(String moddn,
                                  String modattr,
                                  String modval)
                           throws Exception
replaceAttributeValue: replaces a given attribute with a certain value

Parameters:
moddn - String representing the DN to which to replace the attribute value
modattr - String representing the name of the attribute to replace the value for
modval - String representing the desired value for the attribute
Throws:
Exception - when underlying modify operation fails

removeAttributeValue

public void removeAttributeValue(String moddn,
                                 String modattr,
                                 String modval)
                          throws Exception
removeAttributeValue: removes a given attribute value from an entry

Parameters:
moddn - String representing the DN to which to remove the attribute value
modattr - String representing the name of the attribute to change
modval - String representing the value you wish to have removed from the attribute
Throws:
Exception - when underlying modify operation fails

removeAllAttributeValues

public void removeAllAttributeValues(String moddn,
                                     String modattr)
                              throws Exception
removeAllAttributeValues: removes all values for a given attribute

Parameters:
moddn - String representing the DN to which to remove the attribute values
modattr - String representing the name of the attribute to remove all values from
Throws:
Exception - when underlying modify operation fails

flagSet

public boolean flagSet(int flag)
Utility method to see if a flag is set

Parameters:
flag - the flag we want to check for
Returns:
true if that flag is set

querySchema

public Object querySchema(Object source)
                   throws Exception
Query the schema of the LDAP server. If source is null, get the schema for the current Entry. If source is not null, it should be a distinguished name

Specified by:
querySchema in interface ConnectorInterface
Overrides:
querySchema in class Connector
Parameters:
source - A distinguished name
Returns:
The schema
Throws:
Exception - Any Exception thrown by underlying libraries
See Also:
Entry, Vector

getAttributeSyntax

public String getAttributeSyntax(DirContext schema,
                                 String attributeName)
Gets an Attribute Syntax from the LDAP Server

Parameters:
schema - A DirContext
attributeName - Name of the attribute
Returns:
The attributeSyntax value

queryObjectClassAttributes

public Vector<Object> queryObjectClassAttributes(String objectClass)
                                          throws Exception
Look up an objectclass in the LDAP Server.

Parameters:
objectClass - The name of the objectclass
Returns:
A Vector containing all attributes of the object class
Throws:
Exception - Any Exception thrown by the underlying libraries

mapAttributeSyntax

public String mapAttributeSyntax(String oid)
Utility method used for parsing attribute syntax

Parameters:
oid - An oid
Returns:
The name matching that oid

queryNamingContexts

public Vector<Object> queryNamingContexts()
                                   throws Exception
Query the LDAP Server for naming contexts

Returns:
A Vector containing the naming contexts
Throws:
Exception - An exception is thrown if this method fails.

getServerControls

public Vector<Object> getServerControls()
                                 throws Exception
Get the supported server Controls from the LDAP Server

Returns:
The serverControls value
Throws:
Exception - An exception is thrown if this method fails.

getServerInfo

public Entry getServerInfo()
Gets the serverInfo from the LDAP Server

Returns:
The serverInfo value

supportsControl

public boolean supportsControl(String oid)
Check if the LDAP Server supports a Control

Parameters:
oid - The Control oid
Returns:
true if the server supports that Control

supportsExtension

public boolean supportsExtension(String oid)
Check if the LDAP Server supports an Extension

Parameters:
oid - The Extension oid
Returns:
true if the server supports that Extension

supportsPagedResults

public boolean supportsPagedResults()
Check if the LDAP Server supports paged results

Returns:
true if the LDAP Server supports paged results

supportsSorting

public boolean supportsSorting()
Check if the LDAP Server supports sorting

Returns:
true if the LDAP Server supports sorting

supportsVirtualListView

public boolean supportsVirtualListView()
Check if the LDAP Server supports virtual list view

Returns:
true if the LDAP Server supports virtual list view

supportsPersistantSearch

public boolean supportsPersistantSearch()
Check if the LDAP Server supports Persistant Search

Returns:
true if the LDAP Server supports Persistant Search

showServerInfo

public void showServerInfo()
Logs server information, supported controls and naming contexts


getVersion

public String getVersion()
Version information.

Specified by:
getVersion in interface VersionInfoInterface
Returns:
version information

setADPassword

public Attribute setADPassword(Object password)
                        throws UnsupportedEncodingException
setADPassword - Returns an Attribute (JNDI) containing the UNICODE version of a password for ActiveDirectory. The attribute name is pre-defined by AD to UNICODE_PASSWORD.

Parameters:
password - The new aDPassword value
Returns:
Returns an Attribute (JNDI) containing the UNICODE version of a password for ActiveDirectory. The attribute name is pre-defined by AD to UNICODE_PASSWORD.
Throws:
UnsupportedEncodingException - An exception is thrown if the encoding required by Active Directory is not supported on this platform.

rebind

public void rebind(String dn,
                   String password)
            throws NamingException
Attempts to reauthenticate using the currently open connection. Calls rebind(dn,password,null).

Parameters:
dn - the distinguished name to rebind with
password - the password for this distinguished name
Throws:
NamingException - when underlying reconnect function fails

rebind

public void rebind(String dn,
                   String password,
                   String authMethod)
            throws NamingException
Attempts to reauthenticate using the currently open connection.

Parameters:
dn - The DN used in the bind request
password - The password used in the bind request
authMethod - The authentication method
Throws:
NamingException - when underlying reconnect function fails

isDeltaSupported

public boolean isDeltaSupported()
This connector is able to perform delta updates

Specified by:
isDeltaSupported in interface ConnectorInterface
Overrides:
isDeltaSupported in class Connector
Returns:
true

callErrorHookOnAttributeInUseException

public void callErrorHookOnAttributeInUseException(boolean errorHook)
Sets the value for invoking error hook on attribute in use exception

Parameters:
errorHook - value to be set

getCallErrorHook

public boolean getCallErrorHook()
Returns true if Error hooks should be called on AttributeInUseException

Returns:
true if Error hooks should be called on AttributeInUseException