org.apache.lucene.search

Class TopDocsCollector<T extends ScoreDoc>

java.lang.Object

org.apache.lucene.search.TopDocsCollector<T>

All Implemented Interfaces:

Collector

Direct Known Subclasses:

TopFieldCollector, TopScoreDocCollector

public abstract class TopDocsCollector<T extends ScoreDoc>
extends Object
implements 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 any of the methods to provide their own implementation, as well as avoid the use of the priority queue entirely by passing null to TopDocsCollector(PriorityQueue). In that case however, you might want to consider overriding all methods, in order to avoid a NullPointerException.

Field Summary

Fields

Modifier and Type	Field and Description
protected static TopDocs	EMPTY_TOPDOCS This is used in case topDocs() is called with illegal parameters, or there simply aren't (enough) results.
protected PriorityQueue<T>	pq The priority queue which holds the top documents.
protected int	totalHits The total number of documents that the collector encountered.
protected TotalHits.Relation	totalHitsRelation Whether totalHits is exact or a lower bound.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TopDocsCollector(PriorityQueue<T> pq)

Method Summary

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 instances.
TopDocs	topDocs() Returns the top docs that were collected by this collector.
TopDocs	topDocs(int start) Returns the documents in the range [start ..
TopDocs	topDocs(int start, int howMany) Returns the documents in the range [start ..
protected int	topDocsSize() The number of valid PQ entries

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.lucene.search.Collector

getLeafCollector, scoreMode

Field Detail

EMPTY_TOPDOCS

protected static final TopDocs EMPTY_TOPDOCS

This is used in case topDocs() is called with illegal parameters, or there simply aren't (enough) results.

pq

protected final 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.

totalHits

protected int totalHits

The total number of documents that the collector encountered.

totalHitsRelation

protected TotalHits.Relation totalHitsRelation

Whether totalHits is exact or a lower bound.

Constructor Detail

TopDocsCollector

protected TopDocsCollector(PriorityQueue<T> pq)

Method Detail

populateResults

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

Populates the results array with the ScoreDoc instances. 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.

topDocsSize

protected int topDocsSize()

The number of valid PQ entries

topDocs

public TopDocs topDocs()

Returns the top docs that were collected by this collector.

topDocs

public TopDocs topDocs(int start)

Returns the documents in the range [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 TopDocs topDocs(int start,
                       int howMany)

Returns the documents in the range [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.