Class ImportConnector
Steps to implement your own connector class
- Create a new class that inherits from the ImportConnector class.
- Implement the abstract methods:
- Optionally override the following methods:
- To support active monitoring, implement an event listener running on a
separate thread. Start the thread in the
connect
method and stop it in thedisconnect
method. This event listener thread should detect changes in the monitored data source and add them to a list of changes that can be retrieved by TRIPcof via the firstItem/nextItema and loadItem methods. - When running in active monitoring mode, the firstItem and loadItem methods should block and only return when an item change has been detected, or by throwing an exception when a critical error has occurred.
Error Management
The workflow and processing logic of the connectivity framework indexer engine
requires that connector error status can be querired at any time, regardless of
exception state. To ensure that this is done properly, any exception that is
thrown by the connector or indirectly caused by the connector to be thrown must
either be fully handled by the connector or passed to the connectivity framework
via throwError(ConnectorReturnCode,String)
or
throwError(ConnectorReturnCode,String,Throwable)
, or by calling the setError(ag.smaser.trip.cfw.ConnectorReturnCode, java.lang.String)
method prior to returning an error code from a method. Failing to do this may
cause the connectivity framework not to handle the connector's error status correctly.
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract ChangeType
checkItem
(Object dsref, ImportItem item) Check if an item is in need of update.abstract Object
connect
(boolean active) Connect to a data source.abstract void
disconnect
(Object dsref) Disconnect from data source.abstract ImportItem
Retrieve the first item from the data source.getConnectorProperty
(String name) Retrieves the value of a specified connector property.final String
Returns the last connector error message.final int
Returns the last connector error.final Charset
Returns the text encoding that any text output from the connector must have.boolean
hasConnectorProperty
(String name) Checks if a specified connector property exists.int
Initializes the import connector.abstract int
loadItem
(Object dsref, ImportItem item) Load all the data for an item.final void
Prints a debug logging statement to the log.abstract ImportItem
Retrieve the next item from the data source.final int
setConnectorProperty
(String name, String value) Called by the connectivity framework to assign a connector property (as found in the configuration file for the connector).final void
setError
(ConnectorReturnCode code, String msg) Registers an error code and its associated message and passes it along to the logger if one is defined by the connectivity framework.final void
setTextEncoding
(String encName) Called by the Connectivity Framework to assign an output encoding (charset) for text.final void
throwError
(ConnectorReturnCode code, String msg) Logs an error with the connectivity framework and throws it as an exception.final void
throwError
(ConnectorReturnCode code, String msg, Throwable cause) Logs an error with the connectivity framework and throws it as an exception.int
Uninitializes the import connector.
-
Constructor Details
-
ImportConnector
protected ImportConnector()ImportConnector constructor.This constructor just creates an ImportConnector object. It does not perform other initializations. Override the
initializeConnector()
anduninitializeConnector()
methods to customize (un)initialization steps for the connector and data source.- See Also:
-
-
Method Details
-
initializeConnector
Initializes the import connector.The connector implementation may override this method if it needs to perform any one-time initialization operations. If this method is overriden, the overriding version MUST ensure to call this method (i.e. the base class version) as part of its imlementation. For example:
public int initializeConnector() throws ConnectorException { // Call base class version as required super.initializeConnector(); // Custom initialization follows myresource = new MyCustomResourceClass(); // Must use one of the ConnectorReturnCode values as return code return ConnectorReturnCode.Success.getCode(); }
- Returns:
- An integer that corresponds to a value in the
ConnectorReturnCode
enumerated type. - Throws:
ConnectorException
- If initialization failed.- See Also:
-
uninitializeConnector
Uninitializes the import connector.The connector implementation may override this method if it needs to perform any one-time uninitialization operations. If this method is overriden, the overriding version should ensure to call this method (i.e. the base class version) as part of its imlementation. For example:
public int uninitializeConnector() throws ConnectorException { // Custom uninitialization if (myresource != null) { myresource.close(); myresource = null; } // Call base class version super.uninitializeConnector(); // Must use one of the ConnectorReturnCode values as return code return ConnectorReturnCode.Success.getCode(); }
- Returns:
- An integer that corresponds to a value in the
ConnectorReturnCode
enumerated type. - Throws:
ConnectorException
- If initialization failed.- See Also:
-
connect
Connect to a data source.The information required by the connector to perform the actual connection is found in the data source configuration. Data source configuration files are plain text files in key/value property file format found in the conf/cfw.importds.d directory. The property values are accessible by the connector via the
getConnectorProperty
method.If the 'active' parameter is true, the connector is expected to set up a separate thread to monitor the data source for changes using some kind of event mechanism. If the connector does not support active monitoring or of a failure occurs when setting it up, a
ConnectorException
must be thrown using one of the throwError methods.The returned object is used by the connectivity framework as part of the argument list for several of the methods exposed by the connector. This object should not be the 'this' reference, but rather an independent object that is either the data source connection, or other kind of handle to the connection.
- Parameters:
active
- True to start an active monitoring session- Returns:
- Connection handle, a to the outside opaque object that identifies the data source to the connector.
- Throws:
ConnectorException
- if a connection could not be established (must be thrown via one of the throwError methods).- See Also:
-
disconnect
Disconnect from data source.This method is expected not to fail, but a failure that occurs as part of disconnecting can optionally be registered as an error by calling the
setError
method before returning. -
firstItem
Retrieve the first item from the data source.The returned
ImportItem
should only contain metadata about the found item such as change type (updated, deleted or renamed) and either a timestamp or checksum. The main data of the item is expected to be loaded as part of the call to theloadItem
method.If the connector is running in active monitoring mode (as set up in the call to the
connect
method), this method must block until a data source change event is detected and an item becomes available. The blocking wait may exit prematurely if an unrecoverable error occurs.If a failure other than no items found occurs as part of the call to this method, the
setError
method should be called to register the error state before returning.- Parameters:
dsref
- Connection handle as returned from theconnect
method.- Returns:
- An ImportItem instance with the first item data from the data source, or null if no items were found.
- See Also:
-
nextItem
Retrieve the next item from the data source.The returned
ImportItem
should only contain metadata about the found item such as change type (updated, deleted or renamed) and either a timestamp or checksum. The main data of the item is expected to be loaded as part of the call to theloadItem
method.If the connector is running in active monitoring mode (as set up in the call to the
connect
method), this method must block until a data source change event is detected and an item becomes available. The blocking wait may exit prematurely if an unrecoverable error occurs.If a failure other than no items found occurs as part of the call to this method, the
setError
method should be called to register the error state before returning.- Parameters:
dsref
- Connection handle as returned from theconnect
method.- Returns:
- An ImportItem instance with the item data from the data source, or null if no more items are available.
- See Also:
-
checkItem
Check if an item is in need of update.If the item has not changed, the return value should be ChangeType.None.
This method is only called when the connector is running in polling mode and then only when scanning for changes for already retrieved and indexed items.
- Parameters:
dsref
- Connection handle as returned from theconnect
method.item
- Item to check. The provided object is only loaded with the id and (if applicable) timestamp / checksum.- Returns:
- The type of change that has been detected for the item.
- Throws:
ConnectorException
- if an error occurs during the checking of the item (must be thrown via one of the throwError methods).- See Also:
-
loadItem
Load all the data for an item.This method is expected to load the actual value(s) for the item. This method is typically called after
firstItem(java.lang.Object)
and each call tonextItem(java.lang.Object)
, but the connector should be written to allow multiple calls tonextItem(java.lang.Object)
between calls to this method.- Parameters:
dsref
- Connection handle as returned from theconnect
method.item
- Item to load data for (returned bynextItem(java.lang.Object)
orfirstItem(java.lang.Object)
).- Returns:
- An integer that corresponds to a value in the ConnectorReturnCode enumerated type.
-
getLastConnectorErrorCode
public final int getLastConnectorErrorCode()Returns the last connector error.- Returns:
- An integer that corresponds to a value in the ConnectorReturnCode enumerated type
Connector errors are registered when the
setError(ag.smaser.trip.cfw.ConnectorReturnCode, java.lang.String)
,throwError(ConnectorReturnCode,String)
, andthrowError(ConnectorReturnCode,String,Throwable)
methods are called. - See Also:
-
getLastConnectorError
Returns the last connector error message.Connector errors are registered when the
setError(ag.smaser.trip.cfw.ConnectorReturnCode, java.lang.String)
,throwError(ConnectorReturnCode,String)
, andthrowError(ConnectorReturnCode,String,Throwable)
methods are called.- Returns:
- Last connector error message
- See Also:
-
setTextEncoding
Called by the Connectivity Framework to assign an output encoding (charset) for text.The default text encoding is UTF-8.
This method may only be invoked via the Connectivity Framework. The adapter implementation should not use it.
- Parameters:
encName
- Name of encoding (charset)- Throws:
ConnectorException
- With an error code represented by the ConnectorReturnCode enum
-
getTextEncoding
Returns the text encoding that any text output from the connector must have.- Returns:
- A Charset object.
-
setConnectorProperty
Called by the connectivity framework to assign a connector property (as found in the configuration file for the connector).- Parameters:
name
- Name of propertyvalue
- Value of property.- Returns:
- An integer that corresponds to a value in the ConnectorReturnCode enumerated type.
-
hasConnectorProperty
Checks if a specified connector property exists.- Parameters:
name
- Name of property- Returns:
- True if property exists.
-
getConnectorProperty
Retrieves the value of a specified connector property.- Parameters:
name
- Name of property- Returns:
- Property value, as found in the configuration file for the connector.
-
logDebug
Prints a debug logging statement to the log.- Parameters:
msg
- Debug message to write to the log.
-
setError
Registers an error code and its associated message and passes it along to the logger if one is defined by the connectivity framework.- Parameters:
code
- Error codemsg
- Error message
-
throwError
Logs an error with the connectivity framework and throws it as an exception.- Parameters:
code
- Error codemsg
- Error message- Throws:
ConnectorException
- Exception object with the supplied code and message.
-
throwError
public final void throwError(ConnectorReturnCode code, String msg, Throwable cause) throws ConnectorException Logs an error with the connectivity framework and throws it as an exception.- Parameters:
code
- Error codemsg
- Error messagecause
- Inner exception- Throws:
ConnectorException
- Exception object with the supplied code and message wrapping the throwable cause.
-