Package com.documentum.fc.client.search

# Interface IDfQueryProcessor

public interface IDfQueryProcessor
Manages the execution of a query accross multiple sources.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addListener(IDfQueryListener listener)`
  Registers a listener of the query execution.
  `IDfResultsSet`
  `blockingSearch(long timeout)`
  Starts a search and block until the query execution finished.
  `DfApplicationContext`
  `getApplicationContext()`
  Return the application context set by the client application
  `Map<String,String>`
  `getCutoffMessages()`
  Get cutoff messages.
  `List<IDfFacet>`
  `getFacets()`
  Gets the list of facets.
  `IDfQueryStatus`
  `getQueryStatus()`
  Gets the current status of the query.
  `int`
  `getRangeLowerBound()`
  Returns the lower bound of the range defined by the method setRange
  `int`
  `getRangeUpperBound()`
  Returns the upper bound of the range defined by the method setRange
  `IDfResultsSet`
  `getResults()`
  Gets the current list of results.
  `IDfResultsSet`
  `getResults(int from)`
  Gets a subset of the current list of results, from the specified start index (inclusive) to the end of the list.
  `IDfResultsSet`
  `getResults(int from, int to)`
  Get a subset of the current list of results, from the specified start index (inclusive) to the specified end index (exclusive).
  `int`
  `getResultsSize()`
  Gets the size of the current list of results.
  `void`
  `removeListener(IDfQueryListener listener)`
  Unregisters a listener of the query execution.
  `void`
  `search()`
  Asynchronously starts a search.
  `void`
  `setApplicationContext(DfApplicationContext applicationContext)`
  This context contains information that the client application wants to pass along with the query.
  `void`
  `setRange(int lowerBound, int upperBound)`
  The query (IDfQueryBuilder) attached to this query processor will match only the range of results defined by the lower bound and the upper bound specified by this method.
  `void`
  `setResultRaterFactory(IDfResultRaterFactory resultRaterFactory)`
  Sets the IDfResultRaterFactory that replaces the default one implementing the IPR (Incremental Perceptual Ranking) algorithm.
  `void`
  `setResultsSet(IDfModifiableResultsSet resultSet)`
  Sets the result set to populate as a result of this search.
  `void`
  `stop()`
  Stops a running query.

- ## Method Details

  - ### addListener

    void addListener(IDfQueryListener listener)
    Registers a listener of the query execution.
    Parameters:
      `listener` - This listener will be asynchronously notified of new results and events occuring while executing the query.

  - ### removeListener

    void removeListener(IDfQueryListener listener)
    Unregisters a listener of the query execution.
    Parameters:
      `listener` - A listener that has been previously added using addListener method.

  - ### setResultsSet

    void setResultsSet(IDfModifiableResultsSet resultSet)
    Sets the result set to populate as a result of this search. This method is useful to deal with large result sets that may not fit in memory. The default IDfResultsSet implementation maintains results in memory. The IDfQueryProcessor only uses method addResult to populate the result set.
    Parameters:
      `resultSet` - An IDfModifiableResultsSet object specifying the result set value.

  - ### search

    void search()
    Asynchronously starts a search. This method is not blocking, the client should call addListener before calling this method.

  - ### stop

    void stop()
    Stops a running query. For the API client, this call has immediate effect, but internal resources may take some time to be released.

  - ### blockingSearch

    IDfResultsSet blockingSearch(long timeout) throws InterruptedException, DfSearchException
    Starts a search and block until the query execution finished.
    Parameters:
      `timeout` - A maximum time to wait in milliseconds. Set to 0 to have no timeout. Note that each adapter to the sources may have their own timeout, some connection to the sources may timeout earlier.
    Returns:
      The list of results retrieved.
    Throws:
      `InterruptedException` - If this query processor thread is interrupted while waiting for the query results.
      `DfSearchException` - If the timeout elapses, or if an error occurs during the search.
    See Also:
      - `getResults()`

  - ### getQueryStatus

    IDfQueryStatus getQueryStatus()
    Gets the current status of the query.
    Returns:
      An instance reflecting the current status of each source and a global status for the query.

  - ### getResults

    IDfResultsSet getResults()
    Gets the current list of results. It returns a reference to the results list. Results added to the list by the query processor after this call will appear in the list.
    Returns:
      A list of results. This list is partially ordered by relevance for each source (except if a specific order hint has been specified in the query). However, the order between sources is unspecified.

  - ### getResults

    IDfResultsSet getResults(int from)
    Gets a subset of the current list of results, from the specified start index (inclusive) to the end of the list.
    Parameters:
      `from` - The start index of the sublist.
    Returns:
      A list of results. This list is partially ordered by relevance for each source (except if a specific order hint has been specified in the query). However, the order between sources is unspecified.

  - ### getResults

    IDfResultsSet getResults(int from, int to)
    Get a subset of the current list of results, from the specified start index (inclusive) to the specified end index (exclusive).
    Parameters:
      `from` - The start index of the sublist.
      `to` - The end index of the sublist.
    Returns:
      A list of results. This list is partially ordered by relevance for each source (except if a specific order hint has been specified in the query). However, the order between sources is unspecified.

  - ### getResultsSize

    int getResultsSize()
    Gets the size of the current list of results.
    Returns:
      An int representing the results size value.

  - ### getFacets

    List<IDfFacet> getFacets()
    Gets the list of facets.
    Returns:
      A list of facets.

  - ### setResultRaterFactory

    void setResultRaterFactory(IDfResultRaterFactory resultRaterFactory)
    Sets the IDfResultRaterFactory that replaces the default one implementing the IPR (Incremental Perceptual Ranking) algorithm. The IDfResultRaterFactory set will be used by this query processor to compute the rating score of retrieved results.
    Parameters:
      `resultRaterFactory` - The IDfResultRaterFactory to be used by this query processor.

  - ### setRange

    void setRange(int lowerBound, int upperBound) throws DfSearchException
    The query (IDfQueryBuilder) attached to this query processor will match only the range of results defined by the lower bound and the upper bound specified by this method. Several different executions of the same query on different ranges are then possible just by using this method and then starting again the query either in asynchronous or synchronous mode
    Parameters:
      `lowerBound` - the range lower bound; -1 is used to disable the range access
      `upperBound` - the range upper bound; -1 is used to disable the range access
    Throws:
      `DfSearchException`
    See Also:
      - `search()`
      - `A method is available to know if range access is supported by the query builder`
      - `The results can be retrieved using the methods available in IDfQueryProcessor`
      - `getResults()`

  - ### getRangeLowerBound

    int getRangeLowerBound()
    Returns the lower bound of the range defined by the method setRange
    Returns:
    See Also:
      - `setRange(int lowerBound, int upperBound)`

  - ### getRangeUpperBound

    int getRangeUpperBound()
    Returns the upper bound of the range defined by the method setRange
    Returns:
    See Also:
      - `setRange(int lowerBound, int upperBound)`

  - ### setApplicationContext

    void setApplicationContext(DfApplicationContext applicationContext)
    This context contains information that the client application wants to pass along with the query. These information will be used only if the backend is xPlore and if xQuery is generated. These information will be recorded by xPlore in the audit event logged with the query.
    Parameters:
      `applicationContext` -

  - ### getApplicationContext

    DfApplicationContext getApplicationContext()
    Return the application context set by the client application
    Returns:

  - ### getCutoffMessages

    Map<String,String> getCutoffMessages()
    Get cutoff messages.
    Returns:
      The map from docbase sources to cutoff messages.