Class FilterAdapter
- java.lang.Object
-
- ag.smaser.trip.filefilter.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:
- initializeAdapter to perform one-time initialization of the adapter
- uninitializeAdapter to perform one-time uninitialization of the adapter
-
-
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 highlightingboolean
applyHighlighting()
Checks if hit highlighting should be applied to the outputConvertAbility
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 highlightjava.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 highlightvoid
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.
-
-
-
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 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:
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 propertyvalue
- 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 codemsg
- Error message
-
throwError
public final void throwError(FilterReturnCode code, java.lang.String msg) throws FileFilterException
Logs an error and throws it as an exception.- Parameters:
code
- Error codemsg
- Error message- Throws:
FileFilterException
-
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 codemsg
- Error messagecause
- 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 objectword
- 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 datafilename
- Suggested file name for the dataconv
- Conversion state objectdata
- 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 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(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 datafilename
- Suggested file name for the dataconv
- Conversion state objectdata
- 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 objectdata
- 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 objectdata
- 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 objectdata
- 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 objectname
- Property namevalue
- Property value
-
-