Package com.funnelback.filter.api.filters

Interface StringDocumentFilter

All Superinterfaces:

Filter, NamedFilter

public interface StringDocumentFilter
extends Filter

Filter a document where the content is converted to a String.

The document will only call filterAsStringDocument(StringDocument, FilterContext) if both canFilter(NoContentDocument, FilterContext) returns true and the document can be converted into a String.

After a document has been converted into a StringDocument, the encoding of the raw bytes will be UTF-8, if the document defines the encoding type it must be changed to UTF-8.

Method Summary

Modifier and Type	Method	Description
PreFilterCheck	canFilter(NoContentDocument document, FilterContext context)	Checks if the document can be filtered.
default FilterResult	filter(FilterableDocument document, FilterContext context)	Filter method responsible for calling canFilter(NoContentDocument, FilterContext) and filterAsStringDocument(StringDocument, FilterContext)
FilterResult	filterAsStringDocument(StringDocument document, FilterContext context)	Filters the StringDocument

Methods inherited from interface com.funnelback.filter.api.filters.NamedFilter

getFilterName

Method Detail

canFilter

PreFilterCheck canFilter(NoContentDocument document,
                         FilterContext context)

Checks if the document can be filtered.

This provides the filter an opportunity to avoid the filtering method from being called. This can provide some speed up by avoiding a conversion of the document to StringDocument when the document will not be filtered.

Typically this method is used to inspect non content parts of the document to determine if the document looks like something that can be filtered. For example we may check that the document has a mime type of text/text before we attempt to do any filtering of the document.

The result of this method determines if the filter method is called, it is acceptable for this method to return true while the filter method could return FilterResult.skipped(). As it may not be known if the filter should be skipped until the document contents are inspected.

Parameters:

document - which may have its meta data and other non content parts inspected to determine if an attempt should be made to filter the document.

context - under which the filter is running.

Returns:

PreFilterCheck.ATTEMPT_FILTER if the filter method should be called otherwise PreFilterCheck.SKIP_FILTER, to skip this Filter.

filterAsStringDocument

FilterResult filterAsStringDocument(StringDocument document,
                                    FilterContext context)

Filters the StringDocument

Called when canFilter(NoContentDocument, FilterContext) returns PreFilterCheck.ATTEMPT_FILTER

Parameters:

document - to be filtered where the document content has been converted into a String

context - under which the filter is running.

Returns:

the result of executing this filter, the result may be FilterResult.skipped().

filter

default FilterResult filter(FilterableDocument document,
                            FilterContext context)

Filter method responsible for calling canFilter(NoContentDocument, FilterContext) and filterAsStringDocument(StringDocument, FilterContext)

Typically this method should not be overridden.

Filter a document.

Typically the interfaces BytesDocumentFilter or StringDocumentFilter are implemented instead of Filter as they gives easier access to the document content. This interface should be implemented when the filter does not need to read or modify the documents content.

Filtering only throws unchecked exceptions. In the case a unchecked exception is thrown filtering for that document is stopped and the document may or not be stored. When an exception is raised in a filter the filter can choose to:

• Re-throw the exception as a unchecked exception, ideally as a FilterException.
• Return FilterResult.isSkipped() to indicate that the filter should be considered skipped, in the case of a choice filter this will cause it to try the next filter.
• Ignore the exception and return any other type of FilterResult with or without changes to the given document.

If a checked Exception is raised the filter should catch the exception and typically return the original document or return FilterResult.skipped().

Specified by:

filter in interface Filter

Parameters:

document - The document to be filtered.

context - The context the filter is running under.

Returns:

A FilterResult which comes from one of the static methods on FilterResult.