public abstract class

TopDocsCollector

extends Collector
java.lang.Object
   ↳ org.apache.lucene.search.Collector
     ↳ org.apache.lucene.search.TopDocsCollector<T extends org.apache.lucene.search.ScoreDoc>
Known Direct Subclasses

Class Overview

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.

Summary

Fields
protected static final TopDocs EMPTY_TOPDOCS
protected PriorityQueue<T extends ScoreDoc> pq The priority queue which holds the top documents.
protected int totalHits The total number of documents that the collector encountered.
Protected Constructors
TopDocsCollector(PriorityQueue<T> pq)
Public Methods
int getTotalHits()
The total number of documents that matched this query.
final TopDocs topDocs()
Returns the top docs that were collected by this collector.
final TopDocs topDocs(int start, int howMany)
Returns the documents in the rage [start ..
final TopDocs topDocs(int start)
Returns the documents in the rage [start ..
Protected Methods
TopDocs newTopDocs(ScoreDoc[] results, int start)
Returns a TopDocs instance containing the given results.
void populateResults(ScoreDoc[] results, int howMany)
Populates the results array with the ScoreDoc instaces.
[Expand]
Inherited Methods
From class org.apache.lucene.search.Collector
From class java.lang.Object

Fields

protected static final TopDocs EMPTY_TOPDOCS

protected PriorityQueue<T extends ScoreDoc> 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.

protected int totalHits

The total number of documents that the collector encountered.

Protected Constructors

protected TopDocsCollector (PriorityQueue<T> pq)

Public Methods

public int getTotalHits ()

The total number of documents that matched this query.

public final TopDocs topDocs ()

Returns the top docs that were collected by this collector.

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.

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.

Protected Methods

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.

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.