Class ImportConnector

java.lang.Object
ag.smaser.trip.cfw.ImportConnector

public abstract class ImportConnector extends Object
Base class for Java based import connectors.

Steps to implement your own connector class

  1. Create a new class that inherits from the ImportConnector class.
  2. Implement the abstract methods:
  3. Optionally override the following methods:
  4. To support active monitoring, implement an event listener running on a separate thread. Start the thread in the 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.
  5. 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 Details

    • ImportConnector

      protected ImportConnector()
      ImportConnector constructor.

      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.

      See Also:
  • Method Details

    • 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:
    • 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:
    • connect

      public abstract 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:
    • disconnect

      public abstract void disconnect(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.

      Parameters:
      dsref - Connection handle as returned from the connect method.
      See Also:
    • firstItem

      public abstract ImportItem firstItem(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 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.

      Parameters:
      dsref - Connection handle as returned from the connect method.
      Returns:
      An ImportItem instance with the first item data from the data source, or null if no items were found.
      See Also:
    • nextItem

      public abstract ImportItem nextItem(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 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.

      Parameters:
      dsref - Connection handle as returned from the connect method.
      Returns:
      An ImportItem instance with the item data from the data source, or null if no more items are available.
      See Also:
    • checkItem

      public abstract ChangeType checkItem(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 the connect 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

      public abstract int loadItem(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 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.

      Parameters:
      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)).
      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), and throwError(ConnectorReturnCode,String,Throwable) methods are called.

      See Also:
    • getLastConnectorError

      public final 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), and throwError(ConnectorReturnCode,String,Throwable) methods are called.

      Returns:
      Last connector error message
      See Also:
    • setTextEncoding

      public final void setTextEncoding(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 Charset getTextEncoding()
      Returns the text encoding that any text output from the connector must have.
      Returns:
      A Charset object.
    • setConnectorProperty

      public 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).
      Parameters:
      name - Name of property
      value - Value of property.
      Returns:
      An integer that corresponds to a value in the ConnectorReturnCode enumerated type.
    • hasConnectorProperty

      public boolean hasConnectorProperty(String name)
      Checks if a specified connector property exists.
      Parameters:
      name - Name of property
      Returns:
      True if property exists.
    • getConnectorProperty

      public String getConnectorProperty(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(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, 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 code
      msg - Error message
    • throwError

      public final void throwError(ConnectorReturnCode code, String msg) throws ConnectorException
      Logs an error with the connectivity framework and throws it as an exception.
      Parameters:
      code - Error code
      msg - 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 code
      msg - Error message
      cause - Inner exception
      Throws:
      ConnectorException - Exception object with the supplied code and message wrapping the throwable cause.