Class ImportConnector
- java.lang.Object
-
- ag.smaser.trip.cfw.ImportConnector
-
public abstract class ImportConnector extends java.lang.Object
Base class for Java based import connectors.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)
orthrowError(ConnectorReturnCode,String,Throwable)
, or by calling thesetError(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 Modifier Constructor Description protected
ImportConnector()
ImportConnector constructor.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract ChangeType
checkItem(java.lang.Object dsref, ImportItem item)
Check if an item is in need of update.abstract java.lang.Object
connect(boolean active)
Connect to a data source.abstract void
disconnect(java.lang.Object dsref)
Disconnect from data source.abstract ImportItem
firstItem(java.lang.Object dsref)
Retrieve the first item from the data source.java.lang.String
getConnectorProperty(java.lang.String name)
Retrieves the value of a specified connector property.java.lang.String
getLastConnectorError()
Returns the last connector error message.int
getLastConnectorErrorCode()
Returns the last connector error.java.nio.charset.Charset
getTextEncoding()
Returns the text encoding that any text output from the connector must have.boolean
hasConnectorProperty(java.lang.String name)
Checks if a specified connector property exists.int
initializeConnector()
Initializes the import connector.abstract int
loadItem(java.lang.Object dsref, ImportItem item)
Load all the data for an item.void
logDebug(java.lang.String msg)
Prints a debug logging statement to the log.abstract ImportItem
nextItem(java.lang.Object dsref)
Retrieve the next item from the data source.int
setConnectorProperty(java.lang.String name, java.lang.String value)
Called by the connectivity framework to assign a connector property (as found in the configuration file for the connector).void
setError(ConnectorReturnCode code, java.lang.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.void
setTextEncoding(java.lang.String encName)
Called by the Connectivity Framework to assign an output encoding (charset) for text.void
throwError(ConnectorReturnCode code, java.lang.String msg)
Logs an error with the connectivity framework and throws it as an exception.void
throwError(ConnectorReturnCode code, java.lang.String msg, java.lang.Throwable cause)
Logs an error with the connectivity framework and throws it as an exception.int
uninitializeConnector()
Uninitializes the import connector.
-
-
-
Constructor Detail
-
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:
initializeConnector()
-
-
Method Detail
-
initializeConnector
public int initializeConnector() throws ConnectorException
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:
ConnectorReturnCode
-
uninitializeConnector
public int uninitializeConnector() throws ConnectorException
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:
ConnectorReturnCode
-
connect
public abstract java.lang.Object connect(boolean active) throws ConnectorException
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:
getConnectorProperty
,hasConnectorProperty
,disconnect
,throwError(ConnectorReturnCode,String)
,throwError(ConnectorReturnCode,String,Throwable)
-
disconnect
public abstract void disconnect(java.lang.Object dsref)
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
public abstract ImportItem firstItem(java.lang.Object dsref)
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:
ImportItem
,connect
-
nextItem
public abstract ImportItem nextItem(java.lang.Object dsref)
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:
ImportItem
,connect
-
checkItem
public abstract ChangeType checkItem(java.lang.Object dsref, ImportItem item) throws ConnectorException
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:
throwError(ConnectorReturnCode,String)
,throwError(ConnectorReturnCode,String,Throwable)
-
loadItem
public abstract int loadItem(java.lang.Object dsref, ImportItem item)
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:
ConnectorReturnCode
,getLastConnectorError()
-
getLastConnectorError
public final java.lang.String 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:
getLastConnectorErrorCode()
-
setTextEncoding
public final void setTextEncoding(java.lang.String encName) throws ConnectorException
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
public final java.nio.charset.Charset getTextEncoding()
Returns the text encoding that any text output from the connector must have.- Returns:
- A Charset object.
-
setConnectorProperty
public final int setConnectorProperty(java.lang.String name, java.lang.String value)
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
public boolean hasConnectorProperty(java.lang.String name)
Checks if a specified connector property exists.- Parameters:
name
- Name of property- Returns:
- True if property exists.
-
getConnectorProperty
public java.lang.String getConnectorProperty(java.lang.String name)
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
public final void logDebug(java.lang.String msg)
Prints a debug logging statement to the log.- Parameters:
msg
- Debug message to write to the log.
-
setError
public final void setError(ConnectorReturnCode code, java.lang.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.- Parameters:
code
- Error codemsg
- Error message
-
throwError
public final void throwError(ConnectorReturnCode code, java.lang.String msg) throws ConnectorException
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, java.lang.String msg, java.lang.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.
-
-