*
Metamerge logo
Search

Advanced Search
*
*
*
* HOME DOCUMENTS & RESOURCES DOWNLOADS EARLY TECH ACCESS SUPPORT FAQ KNOWN ISSUES OLD VERSIONS
*

com.architech.connector
Class rscConnector

java.lang.Object
  |
  +--com.architech.connector.rscConnector
All Implemented Interfaces:
com.architech.connector.rscConnectorInterface

public abstract class rscConnector
extends java.lang.Object
implements com.architech.connector.rscConnectorInterface

Overview

The rscConnector class provides a default implementation of the rscConnectorInterface. This class also includes useful methods for sub-classing connectors. In general, you should sub-class this class when you write new connectors since it provides a default implementation for most methods. You only have to override data access methods (e.g. getNextEntry etc..) to build a complete connector that handles logging and configuration management. If for some reason you cannot sub-class you could implement the rscConnectorInterface instead. This requires more coding though.

Search Criteria

Worth mentioning is the usage of the rscSearchCriteria class. This class is used as a parameter to various methods (findEntry, deleteEntry ...) and is meant to provide enough information for the connector to identify a single entry in the connected data source. However, some connectors, because of their inner semantics, may not use this parameter if the entry object passed to it contains enough information to identify the target entry. The LDAP connector will typically use the provided distinguished name ($dn) rather than performing a search to obtain the $dn. It is all about unique identifiers really. If the provided entry object contains a unique identifier the connector should use this, if no unique identifier is provided the connector should resort to the information passed in the search entry to locate the target entry.

Dealing with multiple entries

Methods like modEntry and deleteEntry are supposed to modify and delete exactly one single entry. However, there is nothing that prevents a connector from deleting multiple entries but this should be made thouroughly clear in the documentation for the connector. A connector could either delete a single entry if the entry object passed to it contained a unique identifier or the connector could delete all entries found by the search criteria if no unique identifier was passed to it. Again, this kind of connector behavior should be documented well since existing components assume single entry behavior.

If the entry/search results in multiple candidates for modify, delete etc the connector should use the clearFindEntries and addFindEntry methods to signal that the connector was unable to identify a single target entry. For example, the getFindEntryCount method is used by the assembly line to detect this condition and branch off to the Multiple Entries Found hook so the user can deal with those situations. You should also use the getMaxDuplicateEntries method to obtain the maximum number of entries the user wants back in this case.

Using Parsers

If the connector is a transport connector the connector also needs a parser. One such connector is the FileSystem connector that only provides input and output streams. You can use parsers explicitly by loading them or you could include a connector parameter called parser in which case this class will do the loading and initialization of the parser. You only have to call the initParser method and pass the input and/or output streams the parser should use. Then, in your getNextEntry method you call the getParser().readEntry() or getParser().writeEntry(entry) methods. You can also intercept the parser before and after it has read/written an entry. The parser uses buffered readers and writers so if you read or write to the streams used by the parser you should always get the reader/writer objects and use them (e.g. getParser().getWriter() and getParser().getReader()). If not, you may accidently write data to the output stream before the buffered writer has flushed its data to the output stream. See the rspParser class for input/output stream behavior.


Field Summary
static java.lang.String PROPERTY_MESSAGE
           
static java.lang.String PROPERTY_READER
           
static java.lang.String PROPERTY_WRITER
           
 
Fields inherited from interface com.architech.connector.rscConnectorInterface
RCS_ADD, RCS_ALL, RCS_DELETE, RCS_HIERARCHICALSEARCH, RCS_MODIFY, RCS_NONE, RCS_SEARCH
 
Constructor Summary
rscConnector()
          Default constructor.
 
Method Summary
 void abort(java.lang.String errmsg)
           
 void addFindEntry(java.lang.Object entry)
          Adds an entry to the list of duplicate entries found.
 void clearFindEntries()
          Removes all entries from the duplicate entry list.
 void debug(java.lang.String msg)
          Log a message to the connector's log if the debug flag is set.
 boolean debugMode()
          Returns whether debug mode is set or not.
 void deleteEntry(Entry entry, rscSearchCriteria search)
          Deletes an existing entry.
 Entry findEntry(java.lang.Object key, java.lang.Object value)
          Locates an entry based on a key/value pair.
 Entry findEntry(rscSearchCriteria search)
          Finds an existing entry.
 java.lang.Boolean getBoolean(java.lang.Object p1)
          Get boolean returns the value of a config parameter as boolean
 int getCapabilities()
          Returns the connector's capabilities flag.
static java.lang.Object getClassInstance(java.lang.String className)
          Returns a class instance of the specified classname
 java.util.TreeMap getConfiguration()
          Returns the current configuration for this connector as a TreeMap.
 int getFindEntryCount()
          Returns the number of duplicate entries in the list.
 com.architech.rsLog getLog()
          Returns the current log object.
 int getMaxDuplicateEntries()
          Returns the current number of duplicate entries buffered up by the connector.
 com.architech.config.rsConfiguration getMyConfiguration()
          Returns the current configuration for this connector
 java.lang.String getName()
          Returns the name for this connector.
 Entry getNextFindEntry()
          Returns the next entry from the list of duplicate entries found.
 java.lang.String getParam(java.lang.String param)
          Returns the value of param as a java.lang.String object.
 java.lang.String[][] getParameters()
          Returns an array of parameter names and descriptions for the connector's set of parameters.
 com.architech.parser.rspParserInterface getParser()
          Returns the parser interface used by this connector.
 java.lang.Object getProperty(java.lang.Object p1)
          Return a connector property.
 Entry getPushbackEntry()
          Returns the pushed back entry for the connector.
 com.architech.RSInterface getRSInterface()
          Returns the current RSInterface object in use by this connector.
 boolean hasCapabability(int capability)
          Checks if the connector is capable of a specific operation
 boolean hasConfigValue(java.lang.Object p1)
          Return true if we have a configuration value for configName.
 void initialize(java.lang.Object o)
          Initialize the connector.
 void initParser(java.lang.Object is, java.lang.Object os)
          Initialize the connector's parser with input and output streams.
 boolean isExceptionFatal(java.lang.Exception e)
          Returns true if the exception is considered to be fatal.
 void loadParser(java.lang.String className)
          Loads the parser this connector will use.
 void logmsg(java.lang.String msg)
          Log a message to the connector's log.
 void modEntry(Entry entry, rscSearchCriteria search)
          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.
 java.lang.Object querySchema(java.lang.Object source)
          This function translates to whatever means a connector has to discover schema for a connection.
 java.util.Vector queryTables()
          This function translates to whatever means a connector have to discover "tables" for a connection.
 void registerScriptBeans(com.architech.script.scriptEngine se)
          This method is called to register specific objects in the script context.
 void setCapabilities(int capabilities)
          Sets the connectors capabilities to capabilities
 void setConfiguration(java.lang.Object config)
          Sets the configuration for use by this connector.
 void setLog(com.architech.rsLog 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(java.lang.String name)
          Set the name for the connector.
 void setParam(java.lang.String param, java.lang.String value)
          Adds or replaces a connnector configuration parameter.
 void setParentConfiguration(com.architech.config.rsConfiguration parentConfig)
          Sets the parent configuration from which this connector inherits configuration data.
 void setParser(com.architech.parser.rspParserInterface parser)
          Sets the connector's parser.
 void setProperty(java.lang.Object p1, java.lang.Object p2)
          Set connector property.
 void setRSInterface(com.architech.RSInterface rsi)
          Sets the RSInterface for this connector to use.
 void terminate()
          Terminate the connector.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.architech.connector.rscConnectorInterface
getNextEntry, selectEntries
 

Field Detail

PROPERTY_MESSAGE

public static final java.lang.String PROPERTY_MESSAGE

PROPERTY_READER

public static final java.lang.String PROPERTY_READER

PROPERTY_WRITER

public static final java.lang.String PROPERTY_WRITER
Constructor Detail

rscConnector

public rscConnector()
Default constructor. Allocates the properties table for use by getProperty/setProperty methods.
Method Detail

getParameters

public java.lang.String[][] getParameters()
Returns an array of parameter names and descriptions for the connector's set of parameters.
Specified by:
getParameters in interface com.architech.connector.rscConnectorInterface
Returns:
The list of parameter names/descriptions supported by this connector

setLog

public void setLog(com.architech.rsLog logger)
Sets the log object to use for logging messages
Specified by:
setLog in interface com.architech.connector.rscConnectorInterface
Parameters:
logger - The log object
See Also:
rscConnector.logmsg

getLog

public com.architech.rsLog getLog()
Returns the current log object.
Returns:
The current log object or null if no log object exists.
See Also:
rsLog

getBoolean

public java.lang.Boolean getBoolean(java.lang.Object p1)
Get boolean returns the value of a config parameter as boolean

hasConfigValue

public boolean hasConfigValue(java.lang.Object p1)
Return true if we have a configuration value for configName. The value must be present and have a value not equal the blank string.

setMaxDuplicateEntries

public 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.
Specified by:
setMaxDuplicateEntries in interface com.architech.connector.rscConnectorInterface
Parameters:
maxDupEntries - The maximum number of entries to buffer up

getMaxDuplicateEntries

public int getMaxDuplicateEntries()
Returns the current number of duplicate entries buffered up by the connector.
Specified by:
getMaxDuplicateEntries in interface com.architech.connector.rscConnectorInterface
Returns:
Max number of duplicate entries

getPushbackEntry

public Entry getPushbackEntry()
Returns the pushed back entry for the connector. A connector may read one record and then push it back for subsequent getnext calls.
Specified by:
getPushbackEntry in interface com.architech.connector.rscConnectorInterface
Returns:
The pushed back entry or null if no such entry exists.

pushback

public 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 rscTaskComponent when it iterates the connector. The task component first checks if there is a pushback entry available, and if so, returns that entry as the next input entry.
Specified by:
pushback in interface com.architech.connector.rscConnectorInterface
Parameters:
entry - The entry to be returned at the next getnext call

logmsg

public void logmsg(java.lang.String msg)
Log a message to the connector's log. The message is prefixed by the connector's name.
Parameters:
msg - The message to write to the log

debug

public void debug(java.lang.String msg)
Log a message to the connector's log if the debug flag is set.
Parameters:
msg - The message to write to the log

setName

public void setName(java.lang.String name)
Set the name for the connector. This name is used by the logmsg/debug functions.
Specified by:
setName in interface com.architech.connector.rscConnectorInterface
Parameters:
name - The name for the connector

getName

public java.lang.String getName()
Returns the name for this connector.
Specified by:
getName in interface com.architech.connector.rscConnectorInterface
Returns:
The connector's name

getCapabilities

public int getCapabilities()
Returns the connector's capabilities flag. The capabilities flag has a bit for each operation the connector supports.
Specified by:
getCapabilities in interface com.architech.connector.rscConnectorInterface
Returns:
The connector's capabilities flag

setCapabilities

public void setCapabilities(int capabilities)
Sets the connectors capabilities to capabilities
Specified by:
setCapabilities in interface com.architech.connector.rscConnectorInterface
Parameters:
capabilities - The capabilities bits

hasCapabability

public boolean hasCapabability(int capability)
Checks if the connector is capable of a specific operation
Specified by:
hasCapabability in interface com.architech.connector.rscConnectorInterface
Parameters:
capability - The capability to check
Returns:
true if the connector supports it, false otherwise

setParam

public void setParam(java.lang.String param,
                     java.lang.String value)
Adds or replaces a connnector configuration parameter.
Specified by:
setParam in interface com.architech.connector.rscConnectorInterface
Parameters:
param - The parameter name
value - The parameter value

getParam

public java.lang.String getParam(java.lang.String param)
Returns the value of param as a java.lang.String object.
Specified by:
getParam in interface com.architech.connector.rscConnectorInterface
Parameters:
param - The connector configuration parameter name
Returns:
The parameter's value or null if no such parameter exists

setParentConfiguration

public void setParentConfiguration(com.architech.config.rsConfiguration parentConfig)
Sets the parent configuration from which this connector inherits configuration data.
Specified by:
setParentConfiguration in interface com.architech.connector.rscConnectorInterface
Parameters:
parentConfig - The configuration object to inherit from.

setConfiguration

public void setConfiguration(java.lang.Object config)
Sets the configuration for use by this connector.
Specified by:
setConfiguration in interface com.architech.connector.rscConnectorInterface
Parameters:
config - The configuration object (rsConfiguration or TreeMap)

getMyConfiguration

public com.architech.config.rsConfiguration getMyConfiguration()
Returns the current configuration for this connector
Returns:
The configuration object or null if the configuration is not established

getConfiguration

public java.util.TreeMap getConfiguration()
Returns the current configuration for this connector as a TreeMap.
Specified by:
getConfiguration in interface com.architech.connector.rscConnectorInterface
Returns:
The configuration object or null if the configuration is not established

setRSInterface

public void setRSInterface(com.architech.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.
Specified by:
setRSInterface in interface com.architech.connector.rscConnectorInterface
Parameters:
rsi - The RSInterface object

getRSInterface

public com.architech.RSInterface getRSInterface()
Returns the current RSInterface object in use by this connector.
Returns:
Connector's RSInterface object or null

debugMode

public boolean debugMode()
Returns whether debug mode is set or not.
Returns:
The current debug mode

isExceptionFatal

public boolean isExceptionFatal(java.lang.Exception e)
Returns true if the exception is considered to be fatal. This governs wether the assembly line logs the error as a warning or terminates.
Specified by:
isExceptionFatal in interface com.architech.connector.rscConnectorInterface
Parameters:
e - The exception object
Returns:
Whether the exception is fatal or not

getClassInstance

public static java.lang.Object getClassInstance(java.lang.String className)
                                         throws java.lang.Exception
Returns a class instance of the specified classname
Parameters:
className - The fully qualified Java class name
Returns:
A class object for the class
Throws:
Any - exception thrown by the class loader

abort

public void abort(java.lang.String errmsg)
Specified by:
abort in interface com.architech.connector.rscConnectorInterface

loadParser

public void loadParser(java.lang.String className)
                throws java.lang.Exception
Loads the parser this connector will use. A parser is only used when the connector is a transport connector. If the classname is null then this function will use the connector's configuration and RSInterface to find the parser to use.
Parameters:
className - The java class name for the parser to use
Throws:
Any - exception thrown by the class loader

initialize

public void initialize(java.lang.Object o)
                throws java.lang.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.
Specified by:
initialize in interface com.architech.connector.rscConnectorInterface
Parameters:
o - User provided parameter

initParser

public void initParser(java.lang.Object is,
                       java.lang.Object os)
                throws java.lang.Exception
Initialize the connector's parser with input and output streams. If the parser has not been loaded then an attempt is made to load it. The input and output objects may be one of InputStream, OutputStream or Socket.
Parameters:
is - The input object.
os - the output object.
Throws:
Any - exception thrown by the parser
See Also:
rscConnector.loadParser

setParser

public void setParser(com.architech.parser.rspParserInterface parser)
               throws java.io.IOException
Sets the connector's parser.
Parameters:
parser - The parser interface to use

getParser

public com.architech.parser.rspParserInterface getParser()
Returns the parser interface used by this connector.
Returns:
The parser interface object or null if no parser exists

terminate

public void terminate()
Terminate the connector. This function closes all connection and releases all resources used by the connector. This function also calls the parser's closeParser function if a parser is active.
Specified by:
terminate in interface com.architech.connector.rscConnectorInterface

modEntry

public void modEntry(Entry entry,
                     rscSearchCriteria 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.
Specified by:
modEntry in interface com.architech.connector.rscConnectorInterface
Parameters:
entry - The entry data
search - The search criteria used to locate the entry to be modified
Throws:
Any - exceptions thrown by the connector's underlying classes

deleteEntry

public void deleteEntry(Entry entry,
                        rscSearchCriteria search)
                 throws java.lang.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 wheter the search parameter is used or not.
Specified by:
deleteEntry in interface com.architech.connector.rscConnectorInterface
Parameters:
entry - The entry data
search - The search criteria used to locate the entry to be modified
Throws:
Any - exceptions thrown by the connector's underlying classes

findEntry

public Entry findEntry(rscSearchCriteria search)
                throws java.lang.Exception
Finds an existing entry. The search criteria specifies which entry to modify.
Specified by:
findEntry in interface com.architech.connector.rscConnectorInterface
Parameters:
search - The search criteria used to locate the entry to be modified
Throws:
Any - exceptions thrown by the connector's underlying classes

putEntry

public void putEntry(Entry entry)
              throws java.lang.Exception
Adds a new entry.
Specified by:
putEntry in interface com.architech.connector.rscConnectorInterface
Parameters:
entry - The entry data
Throws:
Any - exceptions thrown by the connector's underlying classes

getNextFindEntry

public Entry getNextFindEntry()
                       throws java.lang.Exception
Returns the next entry from the list of duplicate entries found.
Specified by:
getNextFindEntry in interface com.architech.connector.rscConnectorInterface
Returns:
The next entry from the list or null if list is empty or at the end
Throws:
Any - exceptions thrown by the connector's underlying classes

findEntry

public Entry findEntry(java.lang.Object key,
                       java.lang.Object value)
Locates an entry based on a key/value pair. The search is translated to the connector's format for searching.
Parameters:
key - The attribute name
value - The attribute value match
Returns:
The entry found or null if no entries were found

getFindEntryCount

public int getFindEntryCount()
Returns the number of duplicate entries in the list.
Specified by:
getFindEntryCount in interface com.architech.connector.rscConnectorInterface
Returns:
Number of duplicate entries in list

clearFindEntries

public void clearFindEntries()
Removes all entries from the duplicate entry list.

addFindEntry

public void addFindEntry(java.lang.Object entry)
Adds an entry to the list of duplicate entries found.
Parameters:
entry - The entry object to add

querySchema

public java.lang.Object querySchema(java.lang.Object source)
                             throws java.lang.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 column names and their attributes.

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

NameValue
nameThe name of the column/attribute/field ....
syntaxThe syntax or expected value type
sizeIf specified this will give the user a hint as to how long the field may be

Specified by:
querySchema in interface com.architech.connector.rscConnectorInterface
Parameters:
source - The object on which to discover schema. This may be an Entry or a string value
Returns:
A Vector of com.architech.entry.Entry objects describing each entity
See Also:
Entry, Vector

queryTables

public java.util.Vector queryTables()
                             throws java.lang.Exception
This function translates to whatever means a connector have to discover "tables" for a connection. The connector may implement this in which case a Vector of strings is returned. For a database connector this would typically be a list of table/view names the user can access with the current set of parameters. For other connectors this might translate to different concepts.
Returns:
A list of table names
See Also:
Vector

getProperty

public java.lang.Object getProperty(java.lang.Object p1)
Return a connector property. Each connector may have static or runtime properties which can be accessed with this method. Note that connector properties are very different from the connector configuration.
Parameters:
p1 - The property name
Returns:
The property value/object

setProperty

public void setProperty(java.lang.Object p1,
                        java.lang.Object p2)
Set connector property. This method sets a named property to a given value. Note that connector properties are very different from the connector configuration.
Parameters:
p1 - The property name
p2 - The property value

registerScriptBeans

public void registerScriptBeans(com.architech.script.scriptEngine se)
                         throws java.lang.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.
Specified by:
registerScriptBeans in interface com.architech.connector.rscConnectorInterface
Parameters:
se - The script engine context


*
  Metamerge Integrator version 4.5 ©Copyright Metamerge AS 2000-2002 Last edited 2002-04-30 contact us