com.ibm.di.connector
Interface ConnectorInterface

All Known Implementing Classes:

ADChangelogConnector, ADChangelogConnectorv2, AssemblyLineConnector, Axis2WSServerConnector, AxisEasyWSServerConnector, ChangelogConnector, CommandLineConnector, Connector, DBChangelogConnector, DominoAdminPConnector, DominoChangeDetectionConnector, DominoConnector, DominoUsersConnector, DSMLv2SOAPConnector, DSMLv2SOAPServerConnector, EIFConnector, FileConnector, FormEntryConnector, FTPClientConnector, GLAConnector, HTTPClientConnector, HTTPServerConnector, IBMMQConnector, IdMLConnector, IDSChangelogConnector, ITIMAgentConnector, ITRegistryConnector, JDBCConnector, JMSConnector, JMXConnector, JNDIConnector, LDAPConnector, LDAPServerConnector, LogConnector, MailboxConnector, MemQConnector, MQePasswordStoreConnector, NetscapeChangelogConnector, NT4UserMetaDataConnector, OldHTTPCLient, OldHTTPServer, PESConnector, PropertiesConnector, RACConnector, SapALEIDocConnector, SapR3BorConnector, ScriptConnector, ServerNotificationsConnector, SNMPConnector, SNMPServerConnector, StreamConnector, SystemQueueConnector, TAMConnector, TCPConnector, TCPServerConnector, TIMConnector, TimerConnector, URLConnector, UserRegistryConnector, WSReceiverServerConnector, ZOSChangelogConnector

public interface ConnectorInterface

The interface object which all Connectors should implement.

See Also:

Connector

Method Summary

void	deleteEntry(Entry entry, SearchCriteria search) Deletes an existing entry.
Entry	findEntry(SearchCriteria search) Finds an existing entry.
Object	getConfiguration() Returns the current configuration for this connector
Object	getContext() Returns the parent task of the connector - an AssemblyLine object.
int	getFindEntryCount() Returns the number of duplicate entries in the list.
Entry	getFirstFindEntry() Returns the first entry from the list of duplicate entries found.
int	getMaxDuplicateEntries() Returns the current maximum number of duplicate entries buffered up by the connector.
String	getName() Returns the name for this connector.
ConnectorInterface	getNextClient() Server mode - return a clone of self that handles the next client instance when running in server mode.
Entry	getNextEntry() Returns the next Entry from the connector.
Entry	getNextFindEntry() Returns the next entry from the list of duplicate entries found.
String	getParam(String param) Returns the value of a parameter as a java.lang.String object.
Entry	getPushbackEntry() Returns the pushed back entry for the connector.
BaseConfiguration	getRawConnectorConfiguration() Returns the current configuration for the raw connector
void	initialize(Object o) Initialize the connector.
boolean	isDeltaSupported() Returns true if this connector is able to perform delta updates
boolean	isExceptionFatal(Exception e) Returns true if the exception is considered to be fatal.
boolean	isIOException(Throwable e) Returns true if this connector considers the Throwable to be an IOException.
void	modEntry(Entry entry, SearchCriteria search) Modifies an existing entry.
void	modEntry(Entry entry, SearchCriteria search, Entry old) Modifies an existing entry.
void	pushback(Entry e) Make an entry the next entry to be iterated from the connector.
void	putEntry(Entry entry) Adds a new entry to the data source
void	queryOperations(ConnectorConfig config) Discover the operations for a connection given the provided configuration.
Entry	queryReply(Entry entry) Performs a query/reply operations.
Object	querySchema(Object source) This function translates to whatever means a connector has to discover schema for a connection.
void	reconnect(Object o) Reconnect to the underlying data source
void	registerScriptBeans(ScriptEngine se) This method is called to register specific objects in the script context.
void	replyEntry(Entry entry) Send a reply to the connector.
void	selectEntries() Prepare the Connector for sequential read.
void	setConfiguration(Object config) Sets the configuration for use by this connector.
void	setContext(Object aContext) Sets the parent task of the connector - an AssemblyLine object.
void	setCurrent(Entry entry, SearchCriteria search) Change the SearchCriteria search to find the entry sent as a parameter.
void	setLog(Log logger) Sets the Log object to use for logging messages
void	setMaxDuplicateEntries(int mde) Sets the maximum number of duplicate entries to buffer up.
void	setName(String name) Set the name for the connector.
void	setParam(String param, String value) Adds or replaces a connector configuration parameter.
void	setRSInterface(RSInterface rsi) Sets the RSInterface for this connector to use.
void	terminate() Terminate the connector.
void	terminateServer() Interrupts and shuts down the Connector if it runs in Server Mode.

Method Detail

setName

void setName(String name)

Set the name for the connector. This name is used by the logmsg/debug functions.

Parameters:

name - The name for the connector

getName

String getName()

Returns the name for this connector.

Returns:

The connector's name

setParam

void setParam(String param,
              String value)

Adds or replaces a connector configuration parameter.

Parameters:

param - The parameter name

value - The parameter value

getParam

String getParam(String param)

Returns the value of a parameter as a java.lang.String object.

Parameters:

param - The connector configuration parameter name

Returns:

The parameter's value or null if no such parameter exists

setConfiguration

void setConfiguration(Object config)

Sets the configuration for use by this connector.

Parameters:

config - The configuration object (an instance of ConnectorConfig)

getConfiguration

Object getConfiguration()

Returns the current configuration for this connector

Returns:

The configuration object (an instance of ConnectorConfig), or null if the configuration is not established

getRawConnectorConfiguration

BaseConfiguration getRawConnectorConfiguration()

Returns the current configuration for the raw connector

Returns:

The configuration object or null if the configuration is not established

setRSInterface

void setRSInterface(RSInterface rsi)

Sets the RSInterface for this connector to use. The RSInterface object is used to get access system wide parameters such as parser configurations.

Parameters:

rsi - The RSInterface object

setLog

void setLog(Log logger)

Sets the Log object to use for logging messages

Parameters:

logger - The Log object

See Also:

RSInterface.logmsg(String)

setMaxDuplicateEntries

void setMaxDuplicateEntries(int mde)

Sets the maximum number of duplicate entries to buffer up. This is used by the lookup functions when a lookup returns more than one entry.

Parameters:

mde - The maximum number of entries to buffer up

getMaxDuplicateEntries

int getMaxDuplicateEntries()

Returns the current maximum number of duplicate entries buffered up by the connector.

Returns:

Max number of duplicate entries

registerScriptBeans

void registerScriptBeans(ScriptEngine se)
                         throws Exception

This method is called to register specific objects in the script context. If the connector has a parser, the parser's registerScriptBeans method is also called.

Parameters:

se - The script engine context

Throws:

Exception - if an error occurs.

queryOperations

void queryOperations(ConnectorConfig config)
                     throws Exception

Discover the operations for a connection given the provided configuration. The implementation should update the configuration object with available operations. If this method requires the connector to be initialized then the connector must perform init/terminate operations itself.

Parameters:

config - The configuration

Throws:

Exception - if an error occurs in the derived class implementation.

querySchema

Object querySchema(Object source)
                   throws Exception

This function translates to whatever means a connector has to discover schema for a connection. The connector may implement this, in which case a Vector of Entry objects is returned for each column/attribute it discovered. For a database connector this would typically be column names and their attributes.

Each Entry in the Vector returned should contain the following attributes:

Name	Value
name	The name of the column/attribute/field ....
syntax	The syntax or expected value type
size	If specified this will give the user a hint as to how long the field may be

Parameters:

source - The object on which to discover schema. This may be an Entry or a string value

Returns:

A Vector of com.ibm.di.entry.Entry objects describing each entity

Throws:

Exception - if an error while retrieving the schema occurs.

See Also:

Entry, Vector

initialize

void initialize(Object o)
                throws Exception

Initialize the connector. The connector may be passed a parameter of any kind by the user. It is up to the connector to determine whether this object can be used or not. The parameter is typically provided by a user script. When an AssemblyLine initializes it's Connectors, they are passed a ConnectorMode object.

Parameters:

o - User provided parameter

Throws:

Exception - if the initialization of this connector fails.

terminate

void terminate()
               throws Exception

Terminate the connector. This function closes all connection and releases all resources used by the connector. This function also calls the parser's closeParser() method if a parser is active.

Throws:

Exception - if an error occurs.

isExceptionFatal

boolean isExceptionFatal(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. By default all exceptions are fatal.

Parameters:

e - The exception object

Returns:

whether the exception is fatal or not

getNextClient

ConnectorInterface getNextClient()
                                 throws Exception

Server mode - return a clone of self that handles the next client instance when running in server mode. The returned connector may be used in its own thread to handle a "client" request so if the returned instance is returned more than once it must be thread safe.

Returns:

the clone of itself

Throws:

Exception - if an error occurs.

selectEntries

void selectEntries()
                   throws Exception

Prepare the Connector for sequential read. If necessary, create a result set to be used for getNextEntry(). When the Connector is used as an Iterator in an AssemblyLine, this method will be called. Default is an empty method.

Throws:

Exception - if an error occurs.

getNextEntry

Entry getNextEntry()
                   throws Exception

Returns the next Entry from the connector. The entry is populated with attributes and values from the next entry in the input set.

Example:

 var ctor = input.getConnector();
 var entry = ctor.getNextEntry();
 
 for (; entry != null; entry = ctor.getNextEntry()) {
        main.logmsg("Read entry...");
        main.dumpEntry(entry);
 }
 

Returns:

- the next Entry, or null if no more data

Throws:

Exception - if an error occurs.

See Also:

selectEntries()

getFirstFindEntry

Entry getFirstFindEntry()
                        throws Exception

Returns the first entry from the list of duplicate entries found. Also resets the counter for getNextFindEntry

Returns:

The first entry from the list or null if list is empty

Throws:

Exception - if an error occurs.

getNextFindEntry

Entry getNextFindEntry()
                       throws Exception

Returns the next entry from the list of duplicate entries found.

Returns:

The next entry from the list or null if list is empty or at the end

Throws:

Exception - if an error occurs.

putEntry

void putEntry(Entry entry)
              throws Exception

Adds a new entry to the data source

Example:

 var ctor = write.getConnector();
 
 for (i = 0; i < 10; i++) {
        var entry = system.newEntry();
        entry.setAttribute("linenumber", i);
        entry.setAttribute("line", i + " line of text...");
 
        main.logmsg("Writes entry to output...");
        main.dumpEntry(entry);
        ctor.putEntry(entry);
 }
 

Parameters:

entry - The entry data to add

Throws:

Exception - if an error occurs.

replyEntry

void replyEntry(Entry entry)
                throws Exception

Send a reply to the connector.

Parameters:

entry - the information as an Entry

Throws:

Exception - if an error occurs.

modEntry

void modEntry(Entry entry,
              SearchCriteria search)
              throws Exception

Modifies an existing entry. The new entry data is given by the entry parameter and the search criteria specifies which entry to modify.

Parameters:

entry - The entry data

search - The search criteria used to locate the entry to be modified

Throws:

Exception - if an error occurs.

modEntry

void modEntry(Entry entry,
              SearchCriteria search,
              Entry old)
              throws Exception

Modifies an existing entry. The new entry data is given by the entry parameter and the search criteria specifies which entry to modify.

Parameters:

entry - The entry data

search - The search criteria used to locate the entry to be modified

old - The old entry found by the search criteria

Throws:

Exception - if an error occurs.

Since:

5.1

deleteEntry

void deleteEntry(Entry entry,
                 SearchCriteria search)
                 throws Exception

Deletes an existing entry. The search criteria specifies which entry to modify. Some connectors may silently ignore the search criteria. For example, the LDAP connector will use the distinguished name ($dn) from the entry parameter (if it exists) rather than expanding the search criteria and search for the entry. Each connector's inner semantics governs whether the search parameter is used or not.

Parameters:

entry - The entry data

search - The search criteria used to locate the entry to be deleted

Throws:

Exception - if an error occurs.

findEntry

Entry findEntry(SearchCriteria search)
                throws Exception

Finds an existing entry. The search criteria specifies which entry to locate

Here is an example of how to find all people with names starting with 'J' which are from IBM organization in US.

Example:

 var ctor = input.getConnector();
 var crit = new com.ibm.di.SearchCriteria("$dn",
                com.ibm.di.SearchCriteria.SUBSTRING, "c=US,o=IBM");
 crit.addCriteria("name", com.ibm.di.SearchCriteria.INITIAL_STRING, "J");
 crit.addCriteria("objectclass", com.ibm.di.SearchCriteria.SUBSTRING, "person");
 
 var res = ctor.findEntry(crit);
 if (res != null) {
        main.logmsg("Found entry:");
        main.dumpEntry(res);
 } else {
  if( getFindEntryCount()> 1 ){
   main.logmsg("Found these entries:");
   while ( (entry = ctor.getNextFindEntry()) != null ) {
     main.dumpEntry(entry);
   }
  }
  else {
         main.logmsg("Entry not found!");
  }
 }
 

Parameters:

search - The search criteria used to locate the entry to be modified

Returns:

The entry found, or null if no or multiple entries found

Throws:

Exception - if an error occurs.

queryReply

Entry queryReply(Entry entry)
                 throws Exception

Performs a query/reply operations.

Parameters:

entry - The data used in outgoing call

Returns:

The entry returned by the peer

Throws:

Exception - if an error occurs.

getFindEntryCount

int getFindEntryCount()

Returns the number of duplicate entries in the list.

Returns:

Number of duplicate entries in the list

setCurrent

void setCurrent(Entry entry,
                SearchCriteria search)

Change the SearchCriteria search to find the entry sent as a parameter. Used when multiple entries found, and you want to modify or delete one of them. Only a few connectors need to implement this.

Parameters:

entry - The entry we want to find for modification/delete

search - The SearchCriteria we want to change

getPushbackEntry

Entry getPushbackEntry()

Returns the pushed back entry for the connector.

Returns:

The pushed back entry or null if no such entry exists.

See Also:

pushback( Entry )

pushback

void pushback(Entry e)

Make an entry the next entry to be iterated from the connector. This method along with getPushbackEntry is used by the AssemblyLineComponent when it iterates the connector. A connector may read one record and then push it back for the subsequent getNextEntry() call. The task component first checks if there is a pushback entry available, and if so, returns that entry as the next input entry.

Parameters:

e - The entry to be returned at the next getNextEntry() call

reconnect

void reconnect(Object o)
               throws Exception

Reconnect to the underlying data source

Parameters:

o - User provided parameter, which is sent to initialize()

Throws:

Exception - if an error occurs.

See Also:

initialize(Object)

isDeltaSupported

boolean isDeltaSupported()

Returns true if this connector is able to perform delta updates

Returns:

true if delta updates are supported, false otherwise

isIOException

boolean isIOException(Throwable e)

Returns true if this connector considers the Throwable to be an IOException. This is needed because we only try reconnection for IO Exceptions, and some Connectors do not return an IOException for an IO Exception.

Parameters:

e - The Throwable to be determined

Returns:

true if this Throwable is an IO Exception

terminateServer

void terminateServer()
                     throws Exception

Interrupts and shuts down the Connector if it runs in Server Mode. Does not have effect if the Connector is not running in Server Mode.

Throws:

Exception - if an error occurs

getContext

Object getContext()

Returns the parent task of the connector - an AssemblyLine object.

Here is an example hook of how to print the names of all enabled or passive components in the current running assembly line.

Example:

 var ctx = thisConnector.getConnector().getContext();
 var clist = ctx.getConnectors();
 
 for (i = 0; i < clist.size(); i++)
        main.logmsg(clist.get(i).getName());
 

Returns:

the context to which the connector belongs

setContext

void setContext(Object aContext)

Sets the parent task of the connector - an AssemblyLine object.

Parameters:

aContext - the new context to which the connector will belong.