Class FilterAdapter


  • public abstract class FilterAdapter
    extends java.lang.Object
    Base class for Java-based file filter adapters.

    Custom file filter adapters MUST override these methods:

    • checkConversion to indicate if the adapter can convert a named file to a specific target format
    • openConversion to initialize the conversion of a single file
    • convert to perform the conversion
    • closeConversion to release any remaining resources still in use after conversion

    Custom file filter adapters MAY override these methods:

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void addConversionResult​(Conversion conv, byte[] data)
      Pass a block with plain text data from the conversion process to the calling application.
      void addConversionResult​(Conversion conv, byte[] data, int length)
      Pass a block with plain text from the conversion process to the calling application.
      void addConversionResult​(Conversion conv, java.lang.String data)
      Pass a block with plain text from the conversion process to the calling application.
      void addConversionResult​(java.lang.String mimetype, java.lang.String filename, Conversion conv, byte[] data)
      Pass a block with data from the conversion process to the calling application.
      void addConversionResult​(java.lang.String mimetype, java.lang.String filename, Conversion conv, byte[] data, int length)
      Pass a block with data from the conversion process to the calling application.
      void addConversionResult​(java.lang.String mimetype, java.lang.String filename, Conversion conv, java.lang.String data)
      Pass a block with data from the conversion process to the calling application.
      void addExtractedProperty​(Conversion conv, java.lang.String name, java.lang.String value)
      Pass a property name/value pair discovered during the conversion process to the calling application.
      void addHitWord​(Conversion conv, java.lang.String word)
      Called by JNI code to supply search hit terms for highlighting
      boolean applyHighlighting()
      Checks if hit highlighting should be applied to the output
      ConvertAbility checkConversion​(AdapterOutputType targetFormat, java.lang.String filename)
      Checks if the file identified by the supplied file name can possibly be converted to the specified target format.
      abstract void closeConversion​(Conversion conv)
      Called to end a conversion procedure.
      abstract void convert​(Conversion conv, java.lang.String filename)
      Perform the actual conversion.
      java.lang.String getAdapterProperty​(java.lang.String name)
      Retrieves the value of a specified adapter property.
      java.nio.charset.Charset getConvertTextEncoding()
      Returns the text encoding that any text output from the conversion must have.
      java.util.List<java.lang.String> getHitWords()
      Retrieves a list of search hit terms to highlight
      java.lang.String getLastConversionError()
      Returns the error message for the last conversion error.
      int getLastConversionErrorCode()
      Returns the error code for the last conversion error.
      boolean hasAdapterProperty​(java.lang.String name)
      Checks if a specified adapter property exists.
      boolean hasHitWord​(java.lang.String word)
      Checks if a word is among the ones to highlight
      void initializeAdapter​(long nativeinfo)
      Initializes the file filter adapter.
      void logDebug​(java.lang.String msg)
      Prints a debug logging statement to the log.
      abstract void openConversion​(Conversion conv)
      Called to start a conversion procedure.
      void setAdapterProperty​(java.lang.String name, java.lang.String value)
      Called by the Connectivity Framework to assign a file filter property (as found in the configuration file for the adapter).
      void setConvertTextEncoding​(java.lang.String encName)
      Called by the Connectivity Framework to assign an output encoding (charset) for text.
      void setError​(FilterReturnCode 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 throwError​(FilterReturnCode code, java.lang.String msg)
      Logs an error and throws it as an exception.
      void throwError​(FilterReturnCode code, java.lang.String msg, java.lang.Throwable cause)
      Logs an error and throws it as an exception.
      void uninitializeAdapter()
      Uninitializes the file filter adapter.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • initializeAdapter

        public void initializeAdapter​(long nativeinfo)
                               throws FileFilterException
        Initializes the file filter adapter.
        Parameters:
        nativeinfo - Opaque data object to be passed along to some of the JNI-based methods.

        The file filter adapter implementation may override this method if it needs to perform any one-time initialization operations. If this method is overridden, the overriding version MUST ensure to call this method (i.e. the base class version) as part of its implementation. E.g.

        public void initializeAdapter(long nativeinfo) throws FileFilterException
        {
            // Call base class version as required
            super.initializeAdapter(nativeinfo);
         
            // Custom initialization follows
            myresource = new MyCustomResourceClass();
        }
         

        Failure to call the base class version of the initializeAdapter method will result in inconsistent behavior and conversion failures.

        Throws:
        FileFilterException - With an error code represented by the FilterReturnCode enum.
      • uninitializeAdapter

        public void uninitializeAdapter()
                                 throws FileFilterException
        Uninitializes the file filter adapter.

        The file filter adapter implementation may override this method if it needs to perform any one-time uninitialization operations. If this method is overridden, the overriding version should ensure to call this method (i.e. the base class version) as part of its implementation. E.g.

        public void uninitializeAdapter() throws FileFilterException
        {
            // Custom uninitialization
            if (myresource != null)
            {
                myresource.close();
                myresource = null;
            }
        
            // Call base class version as required
            super.uninitializeAdapter();
         
        }
         

        Failure to call the base class version of the uninitializeAdapter method may result in inconsistent behavior and resource leaks.

        Throws:
        FileFilterException - With an error code represented by the FilterReturnCode enum.
      • checkConversion

        public ConvertAbility checkConversion​(AdapterOutputType targetFormat,
                                              java.lang.String filename)
                                       throws FileFilterException
        Checks if the file identified by the supplied file name can possibly be converted to the specified target format.

        The default behavior of this method is to always answer "No". This means that the file filter adapter implementation must override this method in order to return Yes, No or Maybe for any particular conversion.

        Parameters:
        targetFormat - The file format to convert to.
        filename - The name of the file to convert
        Returns:
        An indication of the abilities of the file format adapter regarding this file.
        Throws:
        FileFilterException - With an error code represented by the FilterReturnCode enum.
      • openConversion

        public abstract void openConversion​(Conversion conv)
                                     throws FileFilterException
        Called to start a conversion procedure. Subclasses are expected to perform conversion-specific initialization and pre-validation steps here.
        Parameters:
        conv - Conversion state object
        Throws:
        FileFilterException - Should be thrown when an error during opening occurs.
      • closeConversion

        public abstract void closeConversion​(Conversion conv)
                                      throws FileFilterException
        Called to end a conversion procedure.

        Subclasses are expected to perform clean-up operations here.

        Parameters:
        conv - Conversion state object
        Throws:
        FileFilterException - Should be thrown in exceptional cases when an error occurs during closing. If not strictly fatal, the adapter should ignore errors in this method.
      • convert

        public abstract void convert​(Conversion conv,
                                     java.lang.String filename)
                              throws FileFilterException
        Perform the actual conversion.

        Subclasses must implement this method as the main entry point for the conversion of a single file. The call to this method is preceded by a call to the openConversion method, and followed by a call to the closeConversion method.

        The file filter adapter implementation must call the addConversionResult method to feed converted data back to the caller.

        If the filename is NULL or an empty string, results are to be provided via callbacks.

        Parameters:
        conv - Conversion state object
        filename - Optional name of output file
        Throws:
        FileFilterException
      • getLastConversionErrorCode

        public final int getLastConversionErrorCode()
        Returns the error code for the last conversion error.
        Returns:
        An integer that corresponds to a value in the FilterReturnCode enumerated type.
        See Also:
        FilterReturnCode
      • getLastConversionError

        public final java.lang.String getLastConversionError()
        Returns the error message for the last conversion error.
        Returns:
        Conversion error message.
      • setConvertTextEncoding

        public final void setConvertTextEncoding​(java.lang.String encName)
                                          throws FileFilterException
        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:
        FileFilterException - With an error code represented by the FilterReturnCode enum.
      • getConvertTextEncoding

        public final java.nio.charset.Charset getConvertTextEncoding()
        Returns the text encoding that any text output from the conversion must have.
        Returns:
        A Charset object.
      • setAdapterProperty

        public final void setAdapterProperty​(java.lang.String name,
                                             java.lang.String value)
                                      throws FileFilterException
        Called by the Connectivity Framework to assign a file filter property (as found in the configuration file for the adapter).

        This method may only be invoked via the Connectivity Framework. The adapter implementation should not use it.

        Parameters:
        name - Name of the property
        value - Value of the property.
        Throws:
        FileFilterException - With an error code represented by the FilterReturnCode enum.
      • hasAdapterProperty

        public final boolean hasAdapterProperty​(java.lang.String name)
        Checks if a specified adapter property exists.
        Parameters:
        name - Name of property
        Returns:
        True if property exists
      • getAdapterProperty

        public final java.lang.String getAdapterProperty​(java.lang.String name)
        Retrieves the value of a specified adapter property.
        Parameters:
        name - Name of property
        Returns:
        Property value, as found in the configuration file for the adapter.
      • getHitWords

        public final java.util.List<java.lang.String> getHitWords()
        Retrieves a list of search hit terms to highlight
      • hasHitWord

        public final boolean hasHitWord​(java.lang.String word)
        Checks if a word is among the ones to highlight
        Parameters:
        word - Word to check
        Returns:
        True if the word should be highlighted
      • applyHighlighting

        public final boolean applyHighlighting()
        Checks if hit highlighting should be applied to the output
        Returns:
        True if the result should be highlighted
      • 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​(FilterReturnCode 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​(FilterReturnCode code,
                                     java.lang.String msg,
                                     java.lang.Throwable cause)
                              throws FileFilterException
        Logs an error and throws it as an exception.
        Parameters:
        code - Error code
        msg - Error message
        cause - Inner exception
        Throws:
        FileFilterException
      • addHitWord

        public final void addHitWord​(Conversion conv,
                                     java.lang.String word)
        Called by JNI code to supply search hit terms for highlighting
        Parameters:
        conv - Conversion object
        word - Search hit term to highlight
      • addConversionResult

        public final void addConversionResult​(java.lang.String mimetype,
                                              java.lang.String filename,
                                              Conversion conv,
                                              byte[] data)
        Pass a block with data from the conversion process to the calling application.

        Any text passed via a byte array MUST be in UTF-8.

        Parameters:
        mimetype - Mime type for the data
        filename - Suggested file name for the data
        conv - Conversion state object
        data - Byte array with conversion result.
      • addConversionResult

        public final void addConversionResult​(java.lang.String mimetype,
                                              java.lang.String filename,
                                              Conversion conv,
                                              byte[] data,
                                              int length)
        Pass a block with data from the conversion process to the calling application.

        Any text passed via a byte array MUST be in UTF-8.

        Parameters:
        mimetype - Mime type for the data
        filename - Suggested file name for the data
        conv - Conversion state object
        data - Byte array with conversion result.
        length - Number of bytes from start of byte array to copy
      • addConversionResult

        public final void addConversionResult​(java.lang.String mimetype,
                                              java.lang.String filename,
                                              Conversion conv,
                                              java.lang.String data)
        Pass a block with data from the conversion process to the calling application.
        Parameters:
        mimetype - Mime type for the data
        filename - Suggested file name for the data
        conv - Conversion state object
        data - tring with conversion result.
      • addConversionResult

        public final void addConversionResult​(Conversion conv,
                                              byte[] data)
        Pass a block with plain text data from the conversion process to the calling application.

        The text passed the byte array MUST be in UTF-8.

        Parameters:
        conv - Conversion state object
        data - Byte array with conversion result.
      • addConversionResult

        public final void addConversionResult​(Conversion conv,
                                              byte[] data,
                                              int length)
        Pass a block with plain text from the conversion process to the calling application.

        The text passed via tghe byte array MUST be in UTF-8.

        Parameters:
        conv - Conversion state object
        data - Byte array with conversion result.
        length - Number of bytes from start of byte array to copy
      • addConversionResult

        public final void addConversionResult​(Conversion conv,
                                              java.lang.String data)
        Pass a block with plain text from the conversion process to the calling application.
        Parameters:
        conv - Conversion state object
        data - tring with conversion result.
      • addExtractedProperty

        public final void addExtractedProperty​(Conversion conv,
                                               java.lang.String name,
                                               java.lang.String value)
        Pass a property name/value pair discovered during the conversion process to the calling application.
        Parameters:
        conv - Conversion state object
        name - Property name
        value - Property value