Package org.apache.lucene.search

## Class TimeLimitingCollector

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

- All Implemented Interfaces:
    `Collector`

      public class TimeLimitingCollector
      extends Object
      implements 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`.
  See Also:
    `ExitableDirectoryReader`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `TimeLimitingCollector.TimeExceededException` | Thrown when elapsed search time exceeds allowed search time.
    `static class` | `TimeLimitingCollector.TimerThread` | Thread used to timeout search requests.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TimeLimitingCollector​(Collector collector, Counter clock, long ticksAllowed)` | 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 | Description
    --- | --- | ---
    `static Counter` | `getGlobalCounter()` | Returns the global TimerThreads `Counter`
    `static TimeLimitingCollector.TimerThread` | `getGlobalTimerThread()` | Returns the global `TimeLimitingCollector.TimerThread`.
    `LeafCollector` | `getLeafCollector​(LeafReaderContext context)` | Create a new `collector` to collect the given context.
    `boolean` | `isGreedy()` | Checks if this time limited collector is greedy in collecting the last hit.
    `ScoreMode` | `scoreMode()` | Indicates what features are required from the scorer.
    `void` | `setBaseline()` | Syntactic sugar for `setBaseline(long)` using `Counter.get()` on the clock passed to the constructor.
    `void` | `setBaseline​(long clockTime)` | Sets the baseline for this collector.
    `void` | `setCollector​(Collector collector)` | This is so the same timer can be used with a multi-phase search process such as grouping.
    `void` | `setGreedy​(boolean greedy)` | Sets whether this time limited collector is greedy.

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

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

    - ### Methods inherited from interface org.apache.lucene.search.Collector

      `setWeight`

- - ### Constructor Detail

    - #### TimeLimitingCollector

          public TimeLimitingCollector​(Collector collector,
                                       Counter clock,
                                       long ticksAllowed)

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

  - ### Method Detail

    - #### setBaseline

          public void setBaseline​(long clockTime)

      Sets the baseline for this collector. By default the collectors baseline is initialized once the first reader is passed to the collector. To include operations executed in prior to the actual document collection set the baseline through this method in your prelude.

      Example usage:

             Counter clock = ...;
             long baseline = clock.get();
             // ... prepare search
             TimeLimitingCollector collector = new TimeLimitingCollector(c, clock, numTicks);
             collector.setBaseline(baseline);
             indexSearcher.search(query, collector);

      See Also:
        `setBaseline()`

    - #### setBaseline

          public void setBaseline()

      Syntactic sugar for `setBaseline(long)` using `Counter.get()` on the clock passed to the constructor.

    - #### 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`. However, if the timeout is detected in `getLeafCollector(org.apache.lucene.index.LeafReaderContext)` then no current document is collected.
      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()`

    - #### getLeafCollector

          public LeafCollector getLeafCollector​(LeafReaderContext context)
                                         throws IOException

      Description copied from interface: `Collector`
      Create a new `collector` to collect the given context.
      Specified by:
        `getLeafCollector` in interface `Collector`
      Parameters:
        `context` - next atomic reader context
      Throws:
        `IOException`

    - #### scoreMode

          public ScoreMode scoreMode()

      Description copied from interface: `Collector`
      Indicates what features are required from the scorer.
      Specified by:
        `scoreMode` in interface `Collector`

    - #### setCollector

          public void setCollector​(Collector collector)

      This is so the same timer can be used with a multi-phase search process such as grouping. We don't want to create a new TimeLimitingCollector for each phase because that would reset the timer for each phase. Once time is up subsequent phases need to timeout quickly.
      Parameters:
        `collector` - The actual collector performing search functionality

    - #### getGlobalCounter

          public static Counter getGlobalCounter()

      Returns the global TimerThreads `Counter`

      Invoking this creates may create a new instance of `TimeLimitingCollector.TimerThread` iff the global `TimeLimitingCollector.TimerThread` has never been accessed before. The thread returned from this method is started on creation and will be alive unless you stop the `TimeLimitingCollector.TimerThread` via `TimeLimitingCollector.TimerThread.stopTimer()`.

      Returns:
        the global TimerThreads `Counter`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### getGlobalTimerThread

          public static TimeLimitingCollector.TimerThread getGlobalTimerThread()

      Returns the global `TimeLimitingCollector.TimerThread`.

      Invoking this creates may create a new instance of `TimeLimitingCollector.TimerThread` iff the global `TimeLimitingCollector.TimerThread` has never been accessed before. The thread returned from this method is started on creation and will be alive unless you stop the `TimeLimitingCollector.TimerThread` via `TimeLimitingCollector.TimerThread.stopTimer()`.

      Returns:
        the global `TimeLimitingCollector.TimerThread`
      WARNING: This API is experimental and might change in incompatible ways in the next release.