Package org.apache.lucene.search.matchhighlight

## Class MatchRegionRetriever

- java.lang.Object
- - org.apache.lucene.search.matchhighlight.MatchRegionRetriever

-     public class MatchRegionRetriever
      extends Object

  Utility class to compute a list of "match regions" for a given query, searcher and document(s) using `Matches` API.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `MatchRegionRetriever.FieldValueProvider` | An abstraction that provides document values for a given field.
    `static interface` | `MatchRegionRetriever.MatchOffsetsConsumer` | A callback for accepting a single document (and its associated leaf reader, leaf document ID) and its match offset ranges, as indicated by the `Matches` interface retrieved for the query.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MatchRegionRetriever​(IndexSearcher searcher, Query query, Analyzer analyzer)` | A constructor with the default offset strategy supplier.
    `MatchRegionRetriever​(IndexSearcher searcher, Query query, OffsetsRetrievalStrategySupplier fieldOffsetStrategySupplier)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static OffsetsRetrievalStrategySupplier` | `computeOffsetRetrievalStrategies​(IndexReader reader, Analyzer analyzer)` | Compute default strategies for retrieving offsets from `MatchesIterator` instances for a set of given fields.
    `void` | `highlightDocument​(LeafReaderContext leafReaderContext, int contextDocId, MatchRegionRetriever.FieldValueProvider doc, Predicate<String> acceptField, Map<String,​List<OffsetRange>> outputHighlights)` | Low-level method for retrieving hit ranges for a single document.
    `void` | `highlightDocuments​(PrimitiveIterator.OfInt docIds, MatchRegionRetriever.MatchOffsetsConsumer consumer)` | Low-level, high-efficiency method for highlighting large numbers of documents at once in a streaming fashion.
    `void` | `highlightDocuments​(TopDocs topDocs, MatchRegionRetriever.MatchOffsetsConsumer consumer)` |

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### MatchRegionRetriever

          public MatchRegionRetriever​(IndexSearcher searcher,
                                      Query query,
                                      Analyzer analyzer)
                               throws IOException

      A constructor with the default offset strategy supplier.
      Parameters:
        `analyzer` - An analyzer that may be used to reprocess (retokenize) document fields in the absence of position offsets in the index. Note that the analyzer must return tokens (positions and offsets) identical to the ones stored in the index.
      Throws:
        `IOException`

    - #### MatchRegionRetriever

          public MatchRegionRetriever​(IndexSearcher searcher,
                                      Query query,
                                      OffsetsRetrievalStrategySupplier fieldOffsetStrategySupplier)
                               throws IOException

      Parameters:
        `searcher` - Index searcher to be used for retrieving matches.
        `query` - The query for which matches should be retrieved. The query should be rewritten against the provided searcher.
        `fieldOffsetStrategySupplier` - A custom supplier of per-field `OffsetsRetrievalStrategy` instances.
      Throws:
        `IOException`

  - ### Method Detail

    - #### highlightDocuments

          public void highlightDocuments​(TopDocs topDocs,
                                         MatchRegionRetriever.MatchOffsetsConsumer consumer)
                                  throws IOException

      Throws:
        `IOException`

    - #### highlightDocuments

          public void highlightDocuments​(PrimitiveIterator.OfInt docIds,
                                         MatchRegionRetriever.MatchOffsetsConsumer consumer)
                                  throws IOException

      Low-level, high-efficiency method for highlighting large numbers of documents at once in a streaming fashion.
      Parameters:
        `docIds` - A stream of sorted document identifiers for which hit ranges should be returned.
        `consumer` - A streaming consumer for document-hits pairs.
      Throws:
        `IOException`

    - #### highlightDocument

          public void highlightDocument​(LeafReaderContext leafReaderContext,
                                        int contextDocId,
                                        MatchRegionRetriever.FieldValueProvider doc,
                                        Predicate<String> acceptField,
                                        Map<String,​List<OffsetRange>> outputHighlights)
                                 throws IOException

      Low-level method for retrieving hit ranges for a single document. This method can be used with custom document `MatchRegionRetriever.FieldValueProvider`.
      Throws:
        `IOException`

    - #### computeOffsetRetrievalStrategies

          public static OffsetsRetrievalStrategySupplier computeOffsetRetrievalStrategies​(IndexReader reader,
                                                                                          Analyzer analyzer)

      Compute default strategies for retrieving offsets from `MatchesIterator` instances for a set of given fields.