com.ibm.di.connector
Class JNDIConnector

java.lang.Object
  extended by com.ibm.di.connector.Connector
      extended by com.ibm.di.connector.JNDIConnector
All Implemented Interfaces:
ConnectorInterface, VersionInfoInterface
Direct Known Subclasses:
TIMConnector

public class JNDIConnector
extends Connector
implements ConnectorInterface

The JNDI Connector provides access to a variety of JNDI services; it uses the javax.naming and javax.naming.directory packages to work with different directory services. To reach a specific system, you must install the JNDI driver for that system, for example com.sun.jndi.ldap.LdapCtxFactory for LDAP. The driver is typically distributed as one or more jar or zip files. Place these file in a place where the Java(TM) runtime can reach them, for example, in the /lib/ext directory. This Connector supports Delta Tagging at the Attribute level. This means that provided a previous Connector in the AssemblyLine has provided Delta information at the Attribute level, the JNDI Connector will be able to use it in order to make the changes needed in the target JNDI directory. When using the JNDI Connector for querying an LDAP Server, a SizeLimitExceededException may occur if the number of entries satisfying the search criteria is greater than the maximum limit set by the LDAP Server. To work around this situation, either increase the LDAP Server's maximum result limit, or set the java.naming.batchsize provider parameter to some value smaller than the maximum limit of the server. For more information on the java.naming.batchsize parameter refer to: http://java.sun.com/products/jndi/tutorial/ldap/search/batch.html


Field Summary
 
Fields inherited from class com.ibm.di.connector.Connector
ALL_MODES, myLog, PROPERTY_MESSAGE, PROPERTY_READER, PROPERTY_WRITER
 
Constructor Summary
JNDIConnector()
          Constructor.
 
Method Summary
 void addAttributeValue(java.lang.String moddn, java.lang.String modattr, java.lang.String modval)
          Adds a given value to an attribute
 void deleteEntry(Entry entry, SearchCriteria search)
          Delete an entry.
 Entry findEntry(SearchCriteria search)
          Find an entry matching a SearchCriteria.
 java.lang.String getAttributeSyntax(javax.naming.directory.DirContext schema, java.lang.String attributeName)
          Gets an Attribute Syntax from the schema of the DirContext.
 Entry getCurrentEntry()
          Retrieves current entry.
 Entry getNextEntry()
          Returns the next Entry from the connector.
protected  java.lang.String getSearchFilterAll()
          Retrieves search filter.
 java.lang.String getVersion()
          Version information.
 void initialize(java.lang.Object o)
          Initializes DirContext.
 boolean isDeltaSupported()
          Verifies that delta mode is supported.
 boolean isExceptionFatal(java.lang.Exception e)
          Returns true if the exception is considered to be fatal.
 java.lang.String mapAttributeSyntax(java.lang.String oid)
          Utility method used for parsing attribute syntax
 void modEntry(Entry entry, SearchCriteria search)
          Modifies an existing entry.
 void modEntry(Entry entry, SearchCriteria search, Entry old)
          Modify an Object in the DirContext.
 void putEntry(Entry entry)
          Adds a new entry to the data source.
 java.util.Vector<java.lang.Object> queryObjectClassAttributes(java.lang.String objectClass)
          Look up an objectclass in the schema of the DirContext.
 java.lang.Object querySchema(java.lang.Object source)
          Query the Schema.
 void removeAttribute(java.lang.String moddn, java.lang.String modattr)
          removeAttribute : removes the 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.
protected  void setSearchFilterAll(java.lang.String aSearchFilterAll)
          Sets search filter.
 void terminate()
          Closes the context.
 
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

JNDIConnector

public JNDIConnector()
Constructor.

Method Detail

terminate

public void terminate()
Closes the context.

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

initialize

public void initialize(java.lang.Object o)
                throws java.lang.Exception
Initializes DirContext.

Specified by:
initialize in interface ConnectorInterface
Overrides:
initialize in class Connector
Parameters:
o - User provided parameter
Throws:
java.lang.Exception - if the initialization of this connector fails.

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
Returns the next Entry from the connector. The entry is populated with attributes and values from the next entry in the input set.

Specified by:
getNextEntry in interface ConnectorInterface
Overrides:
getNextEntry in class Connector
Returns:
- the next Entry, or null if no more data
Throws:
java.lang.Exception - if an error occurs.
See Also:
selectEntries()

getCurrentEntry

public Entry getCurrentEntry()
Retrieves current entry.

Returns:
an Entry which contains the current search result

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
Modifies an existing entry. The new entry data is given by the entry parameter and the search criteria specifies which entry to modify. This call is equivalent to modEntry(entry, search, findEntry(search))

Specified by:
modEntry in interface ConnectorInterface
Overrides:
modEntry in class Connector
Parameters:
entry - The entry data
search - The search criteria used to locate the entry to be modified
Throws:
java.lang.Exception - if an error occurs.

modEntry

public void modEntry(Entry entry,
                     SearchCriteria search,
                     Entry old)
              throws java.lang.Exception
Modify an Object in the DirContext. 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 DirContext. 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

deleteEntry

public void deleteEntry(Entry entry,
                        SearchCriteria search)
                 throws java.lang.Exception
Delete an entry. 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)
Returns true if the exception is considered to be fatal. This governs whether the AssemblyLine logs the error as a warning or terminates.

Specified by:
isExceptionFatal in interface ConnectorInterface
Overrides:
isExceptionFatal in class Connector
Parameters:
e - The exception object
Returns:
true if the Exception is one of the following: CommunicationException, CannotProceedException, LimitExceededException, ServiceUnavailableException

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

removeAttribute

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

querySchema

public java.lang.Object querySchema(java.lang.Object source)
                             throws java.lang.Exception
Query the Schema. 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. If nothing is found, an empty Vector is returned.
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 schema of the DirContext.

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 schema of the DirContext.

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 - operation id.
Returns:
The name matching that oid

getVersion

public java.lang.String getVersion()
Version information.

Specified by:
getVersion in interface VersionInfoInterface
Returns:
version information

isDeltaSupported

public boolean isDeltaSupported()
Verifies that delta mode is supported.

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

getSearchFilterAll

protected java.lang.String getSearchFilterAll()
Retrieves search filter.

Returns:
String which contains the SearchFilter

setSearchFilterAll

protected void setSearchFilterAll(java.lang.String aSearchFilterAll)
Sets search filter.

Parameters:
aSearchFilterAll - the String to set the SearchFilter