Expert: Collectors are primarily meant to be used to
/// gather raw results from a search, and implement sorting
/// or custom result filtering, collation, etc.
///
/// As of 2.9, this class replaces the deprecated
/// HitCollector, and offers an API for efficient collection
/// of hits across sequential {@link IndexReader}s. {@link
/// IndexSearcher} advances the collector through each of the
/// sub readers, in an arbitrary order. This results in a
/// higher performance means of collection.
///
/// Lucene's core collectors are derived from Collector.
/// Likely your application can use one of these classes, or
/// subclass {@link TopDocsCollector}, instead of
/// implementing Collector directly:
///
///
///
/// - {@link TopDocsCollector} is an abstract base class
/// that assumes you will retrieve the top N docs,
/// according to some criteria, after collection is
/// done.
///
/// - {@link TopScoreDocCollector} is a concrete subclass
/// {@link TopDocsCollector} and sorts according to score +
/// docID. This is used internally by the {@link
/// IndexSearcher} search methods that do not take an
/// explicit {@link Sort}. It is likely the most frequently
/// used collector.
///
/// - {@link TopFieldCollector} subclasses {@link
/// TopDocsCollector} and sorts according to a specified
/// {@link Sort} object (sort by field). This is used
/// internally by the {@link IndexSearcher} search methods
/// that take an explicit {@link Sort}.
///
/// - {@link TimeLimitingCollector}, which wraps any other
/// Collector and aborts the search if it's taken too much
/// time, will subclass Collector in 3.0 (presently it
/// subclasses the deprecated HitCollector).
///
/// - {@link PositiveScoresOnlyCollector} wraps any other
/// Collector and prevents collection of hits whose score
/// is <= 0.0
///
///
///
/// Collector decouples the score from the collected doc:
/// the score computation is skipped entirely if it's not
/// needed. Collectors that do need the score should
/// implement the {@link #setScorer} method, to hold onto the
/// passed {@link Scorer} instance, and call {@link
/// Scorer#Score()} within the collect method to compute the
/// current hit's score. If your collector may request the
/// score for a single hit multiple times, you should use
/// {@link ScoreCachingWrappingScorer}.
///
/// NOTE: The doc that is passed to the collect
/// method is relative to the current reader. If your
/// collector needs to resolve this to the docID space of the
/// Multi*Reader, you must re-base it by recording the
/// docBase from the most recent setNextReader call. Here's
/// a simple example showing how to collect docIDs into a
/// BitSet:
///
///
/// Searcher searcher = new IndexSearcher(indexReader);
/// final BitSet bits = new BitSet(indexReader.maxDoc());
/// searcher.search(query, new Collector() {
/// private int docBase;
///
/// // ignore scorer
/// public void setScorer(Scorer scorer) {
/// }
///
/// // accept docs out of order (for a BitSet it doesn't matter)
/// public boolean acceptsDocsOutOfOrder() {
/// return true;
/// }
///
/// public void collect(int doc) {
/// bits.set(doc + docBase);
/// }
///
/// public void setNextReader(IndexReader reader, int docBase) {
/// this.docBase = docBase;
/// }
/// });
///
///
/// Not all collectors will need to rebase the docID. For
/// example, a collector that simply counts the total number
/// of hits would skip it.
///
/// NOTE: Prior to 2.9, Lucene silently filtered
/// out hits with score <= 0. As of 2.9, the core Collectors
/// no longer do that. It's very unusual to have such hits
/// (a negative query boost, or function query returning
/// negative custom scores, could cause it to happen). If
/// you need that behavior, use {@link
/// PositiveScoresOnlyCollector}.
///
/// NOTE: This API is experimental and might change
/// in incompatible ways in the next release.
///
///
///