Class ImportConnector


  • public abstract class ImportConnector
    extends java.lang.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 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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

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

        Parameters:
        dsref - Connection handle as returned from the connect method.
        See Also:
        connect, setError
      • 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 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:
        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 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:
        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 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:
        throwError(ConnectorReturnCode,String), throwError(ConnectorReturnCode,String,Throwable)
      • 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 property
        value - 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 code
        msg - 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 code
        msg - 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 code
        msg - Error message
        cause - Inner exception
        Throws:
        ConnectorException - Exception object with the supplied code and message wrapping the throwable cause.