org.apache.lucene.search

## Class TopDocsCollector

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

- Direct Known Subclasses:
    TopFieldCollector, TopScoreDocCollector

      public abstract class TopDocsCollector
      extends Collector

  A base class for all collectors that return a `TopDocs` output. This collector allows easy extension by providing a single constructor which accepts a `PriorityQueue` as well as protected members for that priority queue and a counter of the number of total hits.
  Extending classes can override `topDocs(int, int)` and `getTotalHits()` in order to provide their own implementation.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static TopDocs` | `EMPTY_TOPDOCS`
    `protected PriorityQueue` | `pq` The priority queue which holds the top documents.
    `protected int` | `totalHits` The total number of documents that the collector encountered.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `TopDocsCollector(PriorityQueue pq)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getTotalHits()` The total number of documents that matched this query.
    `protected TopDocs` | `newTopDocs(ScoreDoc[] results, int start)` Returns a `TopDocs` instance containing the given results.
    `protected void` | `populateResults(ScoreDoc[] results, int howMany)` Populates the results array with the ScoreDoc instaces.
    `TopDocs` | `topDocs()` Returns the top docs that were collected by this collector.
    `TopDocs` | `topDocs(int start)` Returns the documents in the rage [start ..
    `TopDocs` | `topDocs(int start, int howMany)` Returns the documents in the rage [start ..

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

      `acceptsDocsOutOfOrder, collect, setNextReader, setScorer`

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

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

- - ### Field Detail

    - #### EMPTY_TOPDOCS

          protected static final TopDocs EMPTY_TOPDOCS

    - #### pq

          protected PriorityQueue pq

      The priority queue which holds the top documents. Note that different implementations of PriorityQueue give different meaning to 'top documents'. HitQueue for example aggregates the top scoring documents, while other PQ implementations may hold documents sorted by other criteria.

    - #### totalHits

          protected int totalHits

      The total number of documents that the collector encountered.

  - ### Constructor Detail

    - #### TopDocsCollector

          protected TopDocsCollector(PriorityQueue pq)

  - ### Method Detail

    - #### populateResults

          protected void populateResults(ScoreDoc[] results,
                                         int howMany)

      Populates the results array with the ScoreDoc instaces. This can be overridden in case a different ScoreDoc type should be returned.

    - #### newTopDocs

          protected TopDocs newTopDocs(ScoreDoc[] results,
                                       int start)

      Returns a `TopDocs` instance containing the given results. If `results` is null it means there are no results to return, either because there were 0 calls to collect() or because the arguments to topDocs were invalid.

    - #### getTotalHits

          public int getTotalHits()

      The total number of documents that matched this query.

    - #### topDocs

          public final TopDocs topDocs()

      Returns the top docs that were collected by this collector.

    - #### topDocs

          public final TopDocs topDocs(int start)

      Returns the documents in the rage [start .. pq.size()) that were collected by this collector. Note that if start >= pq.size(), an empty TopDocs is returned.
      This method is convenient to call if the application always asks for the last results, starting from the last 'page'.
      NOTE: you cannot call this method more than once for each search execution. If you need to call it more than once, passing each time a different `start`, you should call `topDocs()` and work with the returned `TopDocs` object, which will contain all the results this search execution collected.

    - #### topDocs

          public final TopDocs topDocs(int start,
                                       int howMany)

      Returns the documents in the rage [start .. start+howMany) that were collected by this collector. Note that if start >= pq.size(), an empty TopDocs is returned, and if pq.size() - start < howMany, then only the available documents in [start .. pq.size()) are returned.
      This method is useful to call in case pagination of search results is allowed by the search application, as well as it attempts to optimize the memory used by allocating only as much as requested by howMany.
      NOTE: you cannot call this method more than once for each search execution. If you need to call it more than once, passing each time a different range, you should call `topDocs()` and work with the returned `TopDocs` object, which will contain all the results this search execution collected.

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