org.apache.lucene.search

Class TopFieldCollector

java.lang.Object

org.apache.lucene.search.TopDocsCollector<FieldValueHitQueue.Entry>

org.apache.lucene.search.TopFieldCollector

All Implemented Interfaces:

Collector

public abstract class TopFieldCollector
extends TopDocsCollector<FieldValueHitQueue.Entry>

A Collector that sorts by SortField using FieldComparators.

See the create(org.apache.lucene.search.Sort, int, boolean, boolean, boolean) method for instantiating a TopFieldCollector.

WARNING: This API is experimental and might change in incompatible ways in the next release.

Field Summary

Fields inherited from class org.apache.lucene.search.TopDocsCollector

EMPTY_TOPDOCS, pq, totalHits

Method Summary

Methods

Modifier and Type	Method and Description
static TopFieldCollector	create(Sort sort, int numHits, boolean fillFields, boolean trackDocScores, boolean trackMaxScore) Creates a new TopFieldCollector from the given arguments.
static TopFieldCollector	create(Sort sort, int numHits, FieldDoc after, boolean fillFields, boolean trackDocScores, boolean trackMaxScore) Creates a new TopFieldCollector from the given arguments.
boolean	needsScores() Indicates if document scores are needed by this collector.
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.
TopFieldDocs	topDocs() Returns the top docs that were collected by this collector.

Methods inherited from class org.apache.lucene.search.TopDocsCollector

getTotalHits, topDocs, topDocs, topDocsSize

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

Method Detail

needsScores

public boolean needsScores()

Description copied from interface: Collector

Indicates if document scores are needed by this collector.

Returns:

true if scores are needed.

create

public static TopFieldCollector create(Sort sort,
                       int numHits,
                       boolean fillFields,
                       boolean trackDocScores,
                       boolean trackMaxScore)
                                throws IOException

Creates a new TopFieldCollector from the given arguments.

NOTE: The instances returned by this method pre-allocate a full array of length numHits.

Parameters:

sort - the sort criteria (SortFields).

numHits - the number of results to collect.

fillFields - specifies whether the actual field values should be returned on the results (FieldDoc).

trackDocScores - specifies whether document scores should be tracked and set on the results. Note that if set to false, then the results' scores will be set to Float.NaN. Setting this to true affects performance, as it incurs the score computation on each competitive result. Therefore if document scores are not required by the application, it is recommended to set it to false.

trackMaxScore - specifies whether the query's maxScore should be tracked and set on the resulting TopDocs. Note that if set to false, TopDocs.getMaxScore() returns Float.NaN. Setting this to true affects performance as it incurs the score computation on each result. Also, setting this true automatically sets trackDocScores to true as well.

Returns:

a TopFieldCollector instance which will sort the results by the sort criteria.

Throws:

IOException - if there is a low-level I/O error

create

public static TopFieldCollector create(Sort sort,
                       int numHits,
                       FieldDoc after,
                       boolean fillFields,
                       boolean trackDocScores,
                       boolean trackMaxScore)
                                throws IOException

Creates a new TopFieldCollector from the given arguments.

NOTE: The instances returned by this method pre-allocate a full array of length numHits.

Parameters:

sort - the sort criteria (SortFields).

numHits - the number of results to collect.

after - only hits after this FieldDoc will be collected

fillFields - specifies whether the actual field values should be returned on the results (FieldDoc).

trackDocScores - specifies whether document scores should be tracked and set on the results. Note that if set to false, then the results' scores will be set to Float.NaN. Setting this to true affects performance, as it incurs the score computation on each competitive result. Therefore if document scores are not required by the application, it is recommended to set it to false.

trackMaxScore - specifies whether the query's maxScore should be tracked and set on the resulting TopDocs. Note that if set to false, TopDocs.getMaxScore() returns Float.NaN. Setting this to true affects performance as it incurs the score computation on each result. Also, setting this true automatically sets trackDocScores to true as well.

Returns:

a TopFieldCollector instance which will sort the results by the sort criteria.

Throws:

IOException - if there is a low-level I/O error

populateResults

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

Description copied from class: TopDocsCollector

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

Overrides:

populateResults in class TopDocsCollector<FieldValueHitQueue.Entry>

newTopDocs

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

Description copied from class: TopDocsCollector

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.

Overrides:

newTopDocs in class TopDocsCollector<FieldValueHitQueue.Entry>

topDocs

public TopFieldDocs topDocs()

Description copied from class: TopDocsCollector

Returns the top docs that were collected by this collector.

Overrides:

topDocs in class TopDocsCollector<FieldValueHitQueue.Entry>