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

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