org.apache.lucene.search

## Interface LeafCollector

- All Known Implementing Classes:
    FilterLeafCollector, MultiCollectorManager.Collectors.LeafCollectors, SimpleCollector, TotalHitCountCollector

      public interface LeafCollector

  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 `setScorer(org.apache.lucene.search.Scorable)` method, to hold onto the passed `Scorer` instance, and call `Scorable.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 `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:

       IndexSearcher searcher = new IndexSearcher(indexReader);
       final BitSet bits = new BitSet(indexReader.maxDoc());
       searcher.search(query, new Collector() {

         public LeafCollector getLeafCollector(LeafReaderContext context)
             throws IOException {
           final int docBase = context.docBase;
           return new LeafCollector() {

             // ignore scorer
             public void setScorer(Scorer scorer) throws IOException {
             }

             public void collect(int doc) throws IOException {
               bits.set(docBase + doc);
             }

           };
         }

       });

  Not all collectors will need to rebase the docID. For example, a collector that simply counts the total number of hits would skip it.

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

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `collect(int doc)` Called once for every document matching a query, with the unbased document number.
    `default DocIdSetIterator` | `competitiveIterator()` Optionally returns an iterator over competitive documents.
    `void` | `setScorer(Scorable scorer)` Called before successive calls to `collect(int)`.

- - ### Method Detail

    - #### setScorer

          void setScorer(Scorable scorer)
                  throws IOException

      Called before successive calls to `collect(int)`. Implementations that need the score of the current document (passed-in to `collect(int)`), should save the passed-in Scorer and call scorer.score() when needed.
      Throws:
        `IOException`

    - #### collect

          void collect(int doc)
                throws IOException

      Called once for every document matching a query, with the unbased document number.

      Note: The collection of the current segment can be terminated by throwing a `CollectionTerminatedException`. In this case, the last docs of the current `LeafReaderContext` will be skipped and `IndexSearcher` will swallow the exception and continue collection with the next leaf.

      Note: This is called in an inner search loop. For good search performance, implementations of this method should not call `IndexSearcher.doc(int)` or `IndexReader.document(int)` on every hit. Doing so can slow searches by an order of magnitude or more.

      Throws:
        `IOException`

    - #### competitiveIterator

          default DocIdSetIterator competitiveIterator()
                                                throws IOException

      Optionally returns an iterator over competitive documents. Collectors should delegate this method to their comparators if their comparators provide the skipping functionality over non-competitive docs. The default is to return `null` which is interpreted as the collector provide any competitive iterator.
      Throws:
        `IOException`

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