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.