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`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and 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 and 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 and 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.
    `boolean` | `needsScores()` Indicates if document scores are needed by this collector.
    `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`

- - ### 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`

    - #### needsScores

          public boolean needsScores()

      Description copied from interface: `Collector`
      Indicates if document scores are needed by this collector.
      Specified by:
        `needsScores` in interface `Collector`
      Returns:
        `true` if scores are needed.

    - #### 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.

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