com.ibm.di.connector
Class LDAPConnector

java.lang.Object
  com.ibm.di.connector.Connector
      com.ibm.di.connector.LDAPConnector

All Implemented Interfaces:

ConnectorInterface, VersionInfoInterface

Direct Known Subclasses:

ADChangelogConnector, ADChangelogConnectorv2, ChangelogConnector

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(java.lang.String moddn, java.lang.String modattr, java.lang.String modval) Adds a given value to an attribute.
javax.naming.directory.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(java.lang.String compdn, java.lang.String attname, java.lang.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(javax.naming.directory.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
java.lang.String	getAttributeSyntax(javax.naming.directory.DirContext schema, java.lang.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.
javax.naming.ldap.InitialLdapContext	getLdapContext() Returns the InitialLdapContext (Connection to the LDAP Server)
Entry	getNextEntry() Get the next entry that was retrieved by selectEntries().
java.util.Vector<java.lang.Object>	getServerControls() Get the supported server Controls from the LDAP Server
Entry	getServerInfo() Gets the serverInfo from the LDAP Server
java.lang.String	getVersion() Version information.
void	initialize(java.lang.Object o) Initialize the Connector, connect to the LDAP Server
boolean	isDeltaSupported() This connector is able to perform delta updates
boolean	isExceptionFatal(java.lang.Exception e) Utility method, that checks if an Exception thrown by underlying libraries is fatal
java.lang.String	mapAttributeSyntax(java.lang.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(java.lang.String p1, java.lang.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.
java.util.Vector<java.lang.Object>	queryNamingContexts() Query the LDAP Server for naming contexts
java.util.Vector<java.lang.Object>	queryObjectClassAttributes(java.lang.String objectClass) Look up an objectclass in the LDAP Server.
java.lang.Object	querySchema(java.lang.Object source) Query the schema of the LDAP server.
void	rebind(java.lang.String dn, java.lang.String password) Attempts to reauthenticate using the currently open connection.
void	rebind(java.lang.String dn, java.lang.String password, java.lang.String authMethod) Attempts to reauthenticate using the currently open connection.
void	removeAllAttributeValues(java.lang.String moddn, java.lang.String modattr) removeAllAttributeValues: removes all values for a given attribute
void	removeAttributeValue(java.lang.String moddn, java.lang.String modattr, java.lang.String modval) removeAttributeValue: removes a given attribute value from an entry
void	replaceAttributeValue(java.lang.String moddn, java.lang.String modattr, java.lang.String modval) replaceAttributeValue: replaces a given attribute with a certain value
void	selectEntries() Prepare the Connector for sequential read.
javax.naming.directory.Attribute	setADPassword(java.lang.Object password) setADPassword - Returns an Attribute (JNDI) containing the UNICODE version of a password for ActiveDirectory.
void	setsubtreeDeleteSupported(boolean subtreeDeleteSupported) Allows deleting subtrees.
void	showServerInfo() Logs server information, supported controls and naming contexts
boolean	supportsControl(java.lang.String oid) Check if the LDAP Server supports a Control
boolean	supportsExtension(java.lang.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 javax.naming.ldap.InitialLdapContext getLdapContext()

Returns the InitialLdapContext (Connection to the LDAP Server)

Returns:

The connection to the LDAP Server

initialize

public void initialize(java.lang.Object o)
                throws java.lang.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:

java.lang.Exception - Any Exception by the underlying methods to connect to the LDAP Server

selectEntries

public void selectEntries()
                   throws java.lang.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:

java.lang.Exception - Any Exception by the underlying library

getNextEntry

public Entry getNextEntry()
                   throws java.lang.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:

java.lang.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 java.lang.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:

java.lang.Exception - If there is no distinguished name

modEntry

public void modEntry(Entry entry,
                     SearchCriteria search)
              throws java.lang.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:

java.lang.Exception - if an error occurs.

See Also:

modEntry(Entry, SearchCriteria, Entry)

modEntry

public void modEntry(Entry entry,
                     SearchCriteria search,
                     Entry old)
              throws java.lang.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:

java.lang.Exception - If no distinguished name can be found

setsubtreeDeleteSupported

public void setsubtreeDeleteSupported(boolean subtreeDeleteSupported)
                               throws java.lang.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:

java.lang.Exception

deleteEntry

public void deleteEntry(Entry entry,
                        SearchCriteria search)
                 throws java.lang.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:

java.lang.Exception - If no distinguished name can be found.

findEntry

public Entry findEntry(SearchCriteria search)
                throws java.lang.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:

java.lang.Exception - Any Exception thrown by the underlying libraries

isExceptionFatal

public boolean isExceptionFatal(java.lang.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(javax.naming.directory.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 javax.naming.directory.BasicAttributes at2entry(Entry entry,
                                                       boolean removeEmptyAttrs)
                                                throws java.lang.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:

java.lang.Exception - If the userPassword Attribute is multivalued, and the Auto Map AD Password parameter is set

moveEntry

public void moveEntry(java.lang.String p1,
                      java.lang.String p2)
               throws java.lang.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:

java.lang.Exception - If the old entry could not be deleted

java.lang.Exception - If the old entry could be deleted, but the new entry could not be added

compare

public boolean compare(java.lang.String compdn,
                       java.lang.String attname,
                       java.lang.String attvalue)
                throws java.lang.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:

java.lang.Exception - when underlying compare funtion fails

addAttributeValue

public void addAttributeValue(java.lang.String moddn,
                              java.lang.String modattr,
                              java.lang.String modval)
                       throws java.lang.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:

java.lang.Exception - when underlying modify operation fails

replaceAttributeValue

public void replaceAttributeValue(java.lang.String moddn,
                                  java.lang.String modattr,
                                  java.lang.String modval)
                           throws java.lang.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:

java.lang.Exception - when underlying modify operation fails

removeAttributeValue

public void removeAttributeValue(java.lang.String moddn,
                                 java.lang.String modattr,
                                 java.lang.String modval)
                          throws java.lang.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:

java.lang.Exception - when underlying modify operation fails

removeAllAttributeValues

public void removeAllAttributeValues(java.lang.String moddn,
                                     java.lang.String modattr)
                              throws java.lang.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:

java.lang.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 java.lang.Object querySchema(java.lang.Object source)
                             throws java.lang.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:

java.lang.Exception - Any Exception thrown by underlying libraries

See Also:

Entry, Vector

getAttributeSyntax

public java.lang.String getAttributeSyntax(javax.naming.directory.DirContext schema,
                                           java.lang.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 java.util.Vector<java.lang.Object> queryObjectClassAttributes(java.lang.String objectClass)
                                                              throws java.lang.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:

java.lang.Exception - Any Exception thrown by the underlying libraries

mapAttributeSyntax

public java.lang.String mapAttributeSyntax(java.lang.String oid)

Utility method used for parsing attribute syntax

Parameters:

oid - An oid

Returns:

The name matching that oid

queryNamingContexts

public java.util.Vector<java.lang.Object> queryNamingContexts()
                                                       throws java.lang.Exception

Query the LDAP Server for naming contexts

Returns:

A Vector containing the naming contexts

Throws:

java.lang.Exception - An exception is thrown if this method fails.

getServerControls

public java.util.Vector<java.lang.Object> getServerControls()
                                                     throws java.lang.Exception

Get the supported server Controls from the LDAP Server

Returns:

The serverControls value

Throws:

java.lang.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(java.lang.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(java.lang.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 java.lang.String getVersion()

Version information.

Specified by:

getVersion in interface VersionInfoInterface

Returns:

version information

setADPassword

public javax.naming.directory.Attribute setADPassword(java.lang.Object password)
                                               throws java.io.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:

java.io.UnsupportedEncodingException - An exception is thrown if the encoding required by Active Directory is not supported on this platform.

rebind

public void rebind(java.lang.String dn,
                   java.lang.String password)
            throws javax.naming.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:

javax.naming.NamingException - when underlying reconnect function fails

rebind

public void rebind(java.lang.String dn,
                   java.lang.String password,
                   java.lang.String authMethod)
            throws javax.naming.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:

javax.naming.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