org.apache.lucene.search

## Class TimeLimitingCollector

- java.lang.Object
- - org.apache.lucene.search.Collector
  - - org.apache.lucene.search.TimeLimitingCollector

-     public class TimeLimitingCollector
      extends Collector

  The `TimeLimitingCollector` is used to timeout search requests that take longer than the maximum allowed search time limit. After this time is exceeded, the search thread is stopped by throwing a `TimeLimitingCollector.TimeExceededException`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TimeLimitingCollector.TimeExceededException` Thrown when elapsed search time exceeds allowed search time.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `boolean` | `DEFAULT_GREEDY` Default for `isGreedy()`.
    `static int` | `DEFAULT_RESOLUTION` Default timer resolution.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TimeLimitingCollector(Collector collector, long timeAllowed)` Create a TimeLimitedCollector wrapper over another `Collector` with a specified timeout.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `acceptsDocsOutOfOrder()` Return `true` if this collector does not require the matching docIDs to be delivered in int sort order (smallest to largest) to `Collector.collect(int)`.
    `void` | `collect(int doc)` Calls `Collector.collect(int)` on the decorated `Collector` unless the allowed time has passed, in which case it throws an exception.
    `static long` | `getResolution()` Return the timer resolution.
    `boolean` | `isGreedy()` Checks if this time limited collector is greedy in collecting the last hit.
    `void` | `setGreedy(boolean greedy)` Sets whether this time limited collector is greedy.
    `void` | `setNextReader(IndexReader reader, int base)` Called before collecting from each IndexReader.
    `static void` | `setResolution(long newResolution)` Set the timer resolution.
    `void` | `setScorer(Scorer scorer)` Called before successive calls to `Collector.collect(int)`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_RESOLUTION

          public static final int DEFAULT_RESOLUTION

      Default timer resolution.
      See Also:
        `setResolution(long)`, Constant Field Values

    - #### DEFAULT_GREEDY

          public boolean DEFAULT_GREEDY

      Default for `isGreedy()`.
      See Also:
        `isGreedy()`

  - ### Constructor Detail

    - #### TimeLimitingCollector

          public TimeLimitingCollector(Collector collector,
                                       long timeAllowed)

      Create a TimeLimitedCollector wrapper over another `Collector` with a specified timeout.
      Parameters:
        `collector` - the wrapped `Collector`
        `timeAllowed` - max time allowed for collecting hits after which `TimeLimitingCollector.TimeExceededException` is thrown

  - ### Method Detail

    - #### getResolution

          public static long getResolution()

      Return the timer resolution.
      See Also:
        `setResolution(long)`

    - #### setResolution

          public static void setResolution(long newResolution)

      Set the timer resolution. The default timer resolution is 20 milliseconds. This means that a search required to take no longer than 800 milliseconds may be stopped after 780 to 820 milliseconds.
      Note that:
      - Finer (smaller) resolution is more accurate but less efficient.
      - Setting resolution to less than 5 milliseconds will be silently modified to 5 milliseconds.
      - Setting resolution smaller than current resolution might take effect only after current resolution. (Assume current resolution of 20 milliseconds is modified to 5 milliseconds, then it can take up to 20 milliseconds for the change to have effect.

    - #### isGreedy

          public boolean isGreedy()

      Checks if this time limited collector is greedy in collecting the last hit. A non greedy collector, upon a timeout, would throw a `TimeLimitingCollector.TimeExceededException` without allowing the wrapped collector to collect current doc. A greedy one would first allow the wrapped hit collector to collect current doc and only then throw a `TimeLimitingCollector.TimeExceededException`.
      See Also:
        `setGreedy(boolean)`

    - #### setGreedy

          public void setGreedy(boolean greedy)

      Sets whether this time limited collector is greedy.
      Parameters:
        `greedy` - true to make this time limited greedy
      See Also:
        `isGreedy()`

    - #### collect

          public void collect(int doc)
                       throws java.io.IOException

      Calls `Collector.collect(int)` on the decorated `Collector` unless the allowed time has passed, in which case it throws an exception.
      Specified by:
        `collect` in class `Collector`
      Throws:
        `TimeLimitingCollector.TimeExceededException` - if the time allowed has exceeded.
        `java.io.IOException`

    - #### setNextReader

          public void setNextReader(IndexReader reader,
                                    int base)
                             throws java.io.IOException

      Description copied from class: `Collector`
      Called before collecting from each IndexReader. All doc ids in `Collector.collect(int)` will correspond to reader. Add docBase to the current IndexReaders internal document id to re-base ids in `Collector.collect(int)`.
      Specified by:
        `setNextReader` in class `Collector`
      Parameters:
        `reader` - next IndexReader
      Throws:
        `java.io.IOException`

    - #### setScorer

          public void setScorer(Scorer scorer)
                         throws java.io.IOException

      Description copied from class: `Collector`
      Called before successive calls to `Collector.collect(int)`. Implementations that need the score of the current document (passed-in to `Collector.collect(int)`), should save the passed-in Scorer and call scorer.score() when needed.
      Specified by:
        `setScorer` in class `Collector`
      Throws:
        `java.io.IOException`

    - #### acceptsDocsOutOfOrder

          public boolean acceptsDocsOutOfOrder()

      Description copied from class: `Collector`
      Return `true` if this collector does not require the matching docIDs to be delivered in int sort order (smallest to largest) to `Collector.collect(int)`.

      Most Lucene Query implementations will visit matching docIDs in order. However, some queries (currently limited to certain cases of `BooleanQuery`) can achieve faster searching if the `Collector` allows them to deliver the docIDs out of order.

      Many collectors don't mind getting docIDs out of order, so it's important to return `true` here.

      Specified by:
        `acceptsDocsOutOfOrder` in class `Collector`

Copyright © 2000-2016 Apache Software Foundation. All Rights Reserved.