Class FilterAdapter
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:
- initializeAdapter to perform one-time initialization of the adapter
- uninitializeAdapter to perform one-time uninitialization of the adapter
-
Method Summary
Modifier and TypeMethodDescriptionfinal void
addConversionResult
(Conversion conv, byte[] data) Pass a block with plain text data from the conversion process to the calling application.final void
addConversionResult
(Conversion conv, byte[] data, int length) Pass a block with plain text from the conversion process to the calling application.final void
addConversionResult
(Conversion conv, String data) Pass a block with plain text from the conversion process to the calling application.final void
addConversionResult
(String mimetype, String filename, Conversion conv, byte[] data) Pass a block with data from the conversion process to the calling application.final void
addConversionResult
(String mimetype, String filename, Conversion conv, byte[] data, int length) Pass a block with data from the conversion process to the calling application.final void
addConversionResult
(String mimetype, String filename, Conversion conv, String data) Pass a block with data from the conversion process to the calling application.final void
addExtractedProperty
(Conversion conv, String name, String value) Pass a property name/value pair discovered during the conversion process to the calling application.final void
addHitWord
(Conversion conv, String word) Called by JNI code to supply search hit terms for highlightingfinal boolean
Checks if hit highlighting should be applied to the outputcheckConversion
(AdapterOutputType targetFormat, 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, String filename) Perform the actual conversion.final String
getAdapterProperty
(String name) Retrieves the value of a specified adapter property.final Charset
Returns the text encoding that any text output from the conversion must have.Retrieves a list of search hit terms to highlightfinal String
Returns the error message for the last conversion error.final int
Returns the error code for the last conversion error.final boolean
hasAdapterProperty
(String name) Checks if a specified adapter property exists.final boolean
hasHitWord
(String word) Checks if a word is among the ones to highlightvoid
initializeAdapter
(long nativeinfo) Initializes the file filter adapter.final void
Prints a debug logging statement to the log.abstract void
openConversion
(Conversion conv) Called to start a conversion procedure.final void
setAdapterProperty
(String name, String value) Called by the Connectivity Framework to assign a file filter property (as found in the configuration file for the adapter).final void
setConvertTextEncoding
(String encName) Called by the Connectivity Framework to assign an output encoding (charset) for text.final void
setError
(FilterReturnCode 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.final void
throwError
(FilterReturnCode code, String msg) Logs an error and throws it as an exception.final void
throwError
(FilterReturnCode code, String msg, Throwable cause) Logs an error and throws it as an exception.void
Uninitializes the file filter adapter.
-
Method Details
-
initializeAdapter
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
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, 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
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
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
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 objectfilename
- 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:
-
getLastConversionError
Returns the error message for the last conversion error.- Returns:
- Conversion error message.
-
setConvertTextEncoding
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
Returns the text encoding that any text output from the conversion must have.- Returns:
- A Charset object.
-
setAdapterProperty
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 propertyvalue
- Value of the property.- Throws:
FileFilterException
- With an error code represented by the FilterReturnCode enum.
-
hasAdapterProperty
Checks if a specified adapter property exists.- Parameters:
name
- Name of property- Returns:
- True if property exists
-
getAdapterProperty
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
Retrieves a list of search hit terms to highlight -
hasHitWord
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
Prints a debug logging statement to the log.- Parameters:
msg
- Debug message to write to the log.
-
setError
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
Logs an error and throws it as an exception.- Parameters:
code
- Error codemsg
- Error message- Throws:
FileFilterException
-
throwError
public final void throwError(FilterReturnCode code, String msg, Throwable cause) throws FileFilterException Logs an error and throws it as an exception.- Parameters:
code
- Error codemsg
- Error messagecause
- Inner exception- Throws:
FileFilterException
-
addHitWord
Called by JNI code to supply search hit terms for highlighting- Parameters:
conv
- Conversion objectword
- Search hit term to highlight
-
addConversionResult
public final void addConversionResult(String mimetype, 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 datafilename
- Suggested file name for the dataconv
- Conversion state objectdata
- Byte array with conversion result.
-
addConversionResult
public final void addConversionResult(String mimetype, 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 datafilename
- Suggested file name for the dataconv
- Conversion state objectdata
- Byte array with conversion result.length
- Number of bytes from start of byte array to copy
-
addConversionResult
public final void addConversionResult(String mimetype, String filename, Conversion conv, String data) Pass a block with data from the conversion process to the calling application.- Parameters:
mimetype
- Mime type for the datafilename
- Suggested file name for the dataconv
- Conversion state objectdata
- tring with conversion result.
-
addConversionResult
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 objectdata
- Byte array with conversion result.
-
addConversionResult
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 objectdata
- Byte array with conversion result.length
- Number of bytes from start of byte array to copy
-
addConversionResult
Pass a block with plain text from the conversion process to the calling application.- Parameters:
conv
- Conversion state objectdata
- tring with conversion result.
-
addExtractedProperty
Pass a property name/value pair discovered during the conversion process to the calling application.- Parameters:
conv
- Conversion state objectname
- Property namevalue
- Property value
-