public abstract class ImportConnector
extends java.lang.Object
connect
method and stop it in the disconnect
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.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.
Modifier | Constructor and Description |
---|---|
protected |
ImportConnector()
ImportConnector constructor.
|
Modifier and Type | Method and 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.
|
protected ImportConnector()
This constructor just creates an ImportConnector object. It does not
perform other initializations. Override the initializeConnector()
and
uninitializeConnector()
methods to customize (un)initialization steps
for the connector and data source.
initializeConnector()
public int initializeConnector() throws ConnectorException
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(); }
ConnectorReturnCode
enumerated type.ConnectorException
- If initialization failed.ConnectorReturnCode
public int uninitializeConnector() throws ConnectorException
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(); }
ConnectorReturnCode
enumerated type.ConnectorException
- If initialization failed.ConnectorReturnCode
public abstract java.lang.Object connect(boolean active) throws ConnectorException
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.
active
- True to start an active monitoring sessionConnectorException
- if a connection could not be established (must be thrown via one of the throwError methods).getConnectorProperty
,
hasConnectorProperty
,
disconnect
,
throwError(ConnectorReturnCode,String)
,
throwError(ConnectorReturnCode,String,Throwable)
public abstract void disconnect(java.lang.Object dsref)
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.
public abstract ImportItem firstItem(java.lang.Object dsref)
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 the
loadItem
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.
dsref
- Connection handle as returned from the connect
method.ImportItem
,
connect
public abstract ImportItem nextItem(java.lang.Object dsref)
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 the
loadItem
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.
dsref
- Connection handle as returned from the connect
method.ImportItem
,
connect
public abstract ChangeType checkItem(java.lang.Object dsref, ImportItem item) throws ConnectorException
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.
dsref
- Connection handle as returned from the connect
method.item
- Item to check. The provided object is only loaded with the id and (if applicable) timestamp / checksum.ConnectorException
- if an error occurs during the checking of the item (must be thrown via one of the throwError methods).throwError(ConnectorReturnCode,String)
,
throwError(ConnectorReturnCode,String,Throwable)
public abstract int loadItem(java.lang.Object dsref, ImportItem 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 to nextItem(java.lang.Object)
, but the connector should be written to
allow multiple calls to nextItem(java.lang.Object)
between calls to this
method.
dsref
- Connection handle as returned from the connect
method.item
- Item to load data for (returned by nextItem(java.lang.Object)
or firstItem(java.lang.Object)
).public final int getLastConnectorErrorCode()
Connector errors are registered when the setError(ag.smaser.trip.cfw.ConnectorReturnCode, java.lang.String)
,
throwError(ConnectorReturnCode,String)
, and
throwError(ConnectorReturnCode,String,Throwable)
methods
are called.
ConnectorReturnCode
,
getLastConnectorError()
public final java.lang.String getLastConnectorError()
Connector errors are registered when the setError(ag.smaser.trip.cfw.ConnectorReturnCode, java.lang.String)
,
throwError(ConnectorReturnCode,String)
, and
throwError(ConnectorReturnCode,String,Throwable)
methods
are called.
getLastConnectorErrorCode()
public final void setTextEncoding(java.lang.String encName) throws ConnectorException
The default text encoding is UTF-8.
This method may only be invoked via the Connectivity Framework. The adapter implementation should not use it.
encName
- Name of encoding (charset)ConnectorException
- With an error code represented by the ConnectorReturnCode enumpublic final java.nio.charset.Charset getTextEncoding()
public final int setConnectorProperty(java.lang.String name, java.lang.String value)
name
- Name of propertyvalue
- Value of property.public boolean hasConnectorProperty(java.lang.String name)
name
- Name of propertypublic java.lang.String getConnectorProperty(java.lang.String name)
name
- Name of propertypublic final void logDebug(java.lang.String msg)
msg
- Debug message to write to the log.public final void setError(ConnectorReturnCode code, java.lang.String msg)
code
- Error codemsg
- Error messagepublic final void throwError(ConnectorReturnCode code, java.lang.String msg) throws ConnectorException
code
- Error codemsg
- Error messageConnectorException
- Exception object with the supplied code and message.public final void throwError(ConnectorReturnCode code, java.lang.String msg, java.lang.Throwable cause) throws ConnectorException
code
- Error codemsg
- Error messagecause
- Inner exceptionConnectorException
- Exception object with the supplied code and message wrapping the throwable cause.