# Package com.documentum.fc.client.search.filter

package com.documentum.fc.client.search.filter

This package contains interfaces to provide search services filters. A search filter is a plugin that transforms the query and its results. The advantage of using a filter is that one can modify the queries without changing existing applications.
Examples of uses are:

- Add new attributes that can be transformed to internal attributes
- Inject collection directive to make queries more efficient with xPlore
- Set the query locale
- Add computed attributes to the results
- Filter out results
- Removing attributes not supported by the source
- Add logging information for each query

## API

A filter should implement one or several of the following interfaces: `IDfQueryFilter`, `IDfResultFilter`, `IDfFacetFilter` or `IDfCompletionFilter`. The filter can access the execution context through the `IDfContext` interface. It contains session manager, source description and other execution parameters.
The filter can interact with the search service in several ways:

- by returning modified data structure (query, results and facets)
- by modifying some context parameters.
- by sending event. Event can be retrieved on the `IDfQueryStatus` object.

## Deployment

A filter can be deployed in two ways:

- In the application classpath. The filter classes are referenced in a properties file searchfilter.properties. This properties file is also found in the classpath.
- As a SBO. The filter is packaged as a SBO that implements one of the interfaces above. At runtime, the DFC will look for all these SBO and load them as filters.

Several filters can be deployed. However, one cannot control the filters execution order.

## Lifecycle

A filter is instantiated each time a query is executed. If the same filter implements several filters interfaces, it is instantiated only once per query. When multiple sources are queried, it is instantiated once for each search source. The only exception is for external sources where the filter is instantiated and called for all the sources.
A filter class is loaded lazily, when the first query is executed. As a consequence, if an error occur during filter loading it will only be notified at that time. Error due to filter prevent normal query execution. The exception will appear in the query status of `IDfQueryProcessor`.
A filter is called in the DFC Search Service execution pipeline. It is called before the the system generates the query in the source language. As a consequence, it can modify the input query and results, but it has limited control over the query generation itself. One cannot manipulate the DQL satement for example.
The filter interfaces methods are called in the following order:

- filterQuery called once
- filterResults called multilpe times, at least once and filterFacet called one or zero times. The order between facets and results calls is not guaranted. Today filterFacet is called first, but it may change in the future
- onComplete called once

## Threading

For Docbase, only one thread calls the filter instance. For external sources, the filter instance can be called concurrently by different threads.

## Exceptions

If an exception occur during the execution of a filter, the query execution is aborted. Such an exception are reported in the `IDfQueryStatus` object as intrenal failure. The filter can also throw a `com.documentum.fc.client.search.DfFilterException` to report user input error. In this case, it is transform to the appropriate error status (syntax error, login failed...).

To access Java, Visual Basic and C++ DFC sample code, please visit the Documentum Developer Program.

- Related Packages
  Package
  Description
  com.documentum.fc.client.search
  Provides classes and interfaces for constructing and running search queries against multiple content repositories as well as external information sources (optional).
- Class
  Description
  DfFilterException
  An exception raised by a filter.
  DfFilterException.FilterExceptionType
  Type of error
  IDfCompletionFilter
  A filter implements this interface to be notify of the query completion.
  IDfContext
  Context for filters.
  IDfFacetFilter
  A filter can implement this interface to transform facets.
  IDfFilterOrderDependency
  Implementing this interface allow a filter to provide execution order information.
  IDfFilterOrderDependency.Dependency
  IDfGenerationContext
  Provide context about the generation of the query.
  IDfGenerationContext.Language
  IDfQueryFilter
  A filter that can transform a query
  IDfResultFilter
  A filter that can transform search results.