TimeLimitingCollector (Lucene 3.6.2 API)
Keywords: org.apache.lucene.search.TimeLimitingCollector class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
`static class` | `TimeLimitingCollector.TimeExceededException` Thrown when elapsed search time exceeds allowed search time.
`static class` | `TimeLimitingCollector.TimerThread`

Constructor Summary
`TimeLimitingCollector(Collector collector, Counter clock, long ticksAllowed)` Create a TimeLimitedCollector wrapper over another `Collector` with a specified timeout.

Method Summary
`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 Counter` | `getGlobalCounter()` Returns the global TimerThreads `Counter`
`static TimeLimitingCollector.TimerThread` | `getGlobalTimerThread()` Returns the global `TimeLimitingCollector.TimerThread`.
`boolean` | `isGreedy()` Checks if this time limited collector is greedy in collecting the last hit.
`void` | `setBaseline()` Syntactic sugar for `setBaseline(long)` using `Counter.get()` on the clock passed to the construcutor.
`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.
`void` | `setNextReader(IndexReader reader, int base)` Called before collecting from each IndexReader.
`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`

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);

  Parameters:
    `clockTime` -
  See Also:
    `setBaseline()`

### setBaseline

    public void setBaseline()

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

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

### setNextReader

    public void setNextReader(IndexReader reader,
                              int base)
                       throws 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:
    `IOException`

### setScorer

    public void setScorer(Scorer scorer)
                   throws 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:
    `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`

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD