org.apache.lucene.search.highlight

## Class Highlighter

- java.lang.Object
- - org.apache.lucene.search.highlight.Highlighter

-     public class Highlighter
      extends java.lang.Object

  Class used to markup highlighted terms found in the best sections of a text, using configurable `Fragmenter`, `Scorer`, `Formatter`, `Encoder` and tokenizers.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_MAX_CHARS_TO_ANALYZE`
    `static int` | `DEFAULT_MAX_DOC_BYTES_TO_ANALYZE` Deprecated. See `DEFAULT_MAX_CHARS_TO_ANALYZE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Highlighter(Formatter formatter, Encoder encoder, Scorer fragmentScorer)`
    `Highlighter(Formatter formatter, Scorer fragmentScorer)`
    `Highlighter(Scorer fragmentScorer)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `getBestFragment(Analyzer analyzer, java.lang.String fieldName, java.lang.String text)` Highlights chosen terms in a text, extracting the most relevant section.
    `java.lang.String` | `getBestFragment(TokenStream tokenStream, java.lang.String text)` Highlights chosen terms in a text, extracting the most relevant section.
    `java.lang.String[]` | `getBestFragments(Analyzer analyzer, java.lang.String text, int maxNumFragments)` Deprecated. This method incorrectly hardcodes the choice of fieldname. Use the method of the same name that takes a fieldname.
    `java.lang.String[]` | `getBestFragments(Analyzer analyzer, java.lang.String fieldName, java.lang.String text, int maxNumFragments)` Highlights chosen terms in a text, extracting the most relevant sections.
    `java.lang.String[]` | `getBestFragments(TokenStream tokenStream, java.lang.String text, int maxNumFragments)` Highlights chosen terms in a text, extracting the most relevant sections.
    `java.lang.String` | `getBestFragments(TokenStream tokenStream, java.lang.String text, int maxNumFragments, java.lang.String separator)` Highlights terms in the text , extracting the most relevant sections and concatenating the chosen fragments with a separator (typically "...").
    `TextFragment[]` | `getBestTextFragments(TokenStream tokenStream, java.lang.String text, boolean mergeContiguousFragments, int maxNumFragments)` Low level api to get the most relevant (formatted) sections of the document.
    `Encoder` | `getEncoder()`
    `Scorer` | `getFragmentScorer()`
    `int` | `getMaxDocBytesToAnalyze()` Deprecated. See `getMaxDocCharsToAnalyze()`, since this value has always counted on chars. They both set the same internal value, however
    `int` | `getMaxDocCharsToAnalyze()`
    `Fragmenter` | `getTextFragmenter()`
    `void` | `setEncoder(Encoder encoder)`
    `void` | `setFragmentScorer(Scorer scorer)`
    `void` | `setMaxDocBytesToAnalyze(int byteCount)` Deprecated. See `setMaxDocCharsToAnalyze(int)`, since this value has always counted chars
    `void` | `setMaxDocCharsToAnalyze(int maxDocCharsToAnalyze)`
    `void` | `setTextFragmenter(Fragmenter fragmenter)`

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

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

- - ### Field Detail

    - #### DEFAULT_MAX_CHARS_TO_ANALYZE

          public static final int DEFAULT_MAX_CHARS_TO_ANALYZE

      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_DOC_BYTES_TO_ANALYZE

          public static final int DEFAULT_MAX_DOC_BYTES_TO_ANALYZE

      Deprecated. See `DEFAULT_MAX_CHARS_TO_ANALYZE`
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Highlighter

          public Highlighter(Scorer fragmentScorer)

    - #### Highlighter

          public Highlighter(Formatter formatter,
                             Scorer fragmentScorer)

    - #### Highlighter

          public Highlighter(Formatter formatter,
                             Encoder encoder,
                             Scorer fragmentScorer)

  - ### Method Detail

    - #### getBestFragment

          public final java.lang.String getBestFragment(Analyzer analyzer,
                                                        java.lang.String fieldName,
                                                        java.lang.String text)
                                                 throws java.io.IOException,
                                                        InvalidTokenOffsetsException

      Highlights chosen terms in a text, extracting the most relevant section. This is a convenience method that calls `getBestFragment(TokenStream, String)`
      Parameters:
        `analyzer` - the analyzer that will be used to split `text` into chunks
        `text` - text to highlight terms in
        `fieldName` - Name of field used to influence analyzer's tokenization policy
      Returns:
        highlighted text fragment or null if no terms found
      Throws:
        `InvalidTokenOffsetsException` - thrown if any token's endOffset exceeds the provided text's length
        `java.io.IOException`

    - #### getBestFragment

          public final java.lang.String getBestFragment(TokenStream tokenStream,
                                                        java.lang.String text)
                                                 throws java.io.IOException,
                                                        InvalidTokenOffsetsException

      Highlights chosen terms in a text, extracting the most relevant section. The document text is analysed in chunks to record hit statistics across the document. After accumulating stats, the fragment with the highest score is returned
      Parameters:
        `tokenStream` - a stream of tokens identified in the text parameter, including offset information. This is typically produced by an analyzer re-parsing a document's text. Some work may be done on retrieving TokenStreams more efficiently by adding support for storing original text position data in the Lucene index but this support is not currently available (as of Lucene 1.4 rc2).
        `text` - text to highlight terms in
      Returns:
        highlighted text fragment or null if no terms found
      Throws:
        `InvalidTokenOffsetsException` - thrown if any token's endOffset exceeds the provided text's length
        `java.io.IOException`

    - #### getBestFragments

          public final java.lang.String[] getBestFragments(Analyzer analyzer,
                                                           java.lang.String text,
                                                           int maxNumFragments)
                                                    throws java.io.IOException,
                                                           InvalidTokenOffsetsException

      Deprecated. This method incorrectly hardcodes the choice of fieldname. Use the method of the same name that takes a fieldname.
      Highlights chosen terms in a text, extracting the most relevant sections. This is a convenience method that calls `getBestFragments(TokenStream, String, int)`
      Parameters:
        `analyzer` - the analyzer that will be used to split `text` into chunks
        `text` - text to highlight terms in
        `maxNumFragments` - the maximum number of fragments.
      Returns:
        highlighted text fragments (between 0 and maxNumFragments number of fragments)
      Throws:
        `InvalidTokenOffsetsException` - thrown if any token's endOffset exceeds the provided text's length
        `java.io.IOException`

    - #### getBestFragments

          public final java.lang.String[] getBestFragments(Analyzer analyzer,
                                                           java.lang.String fieldName,
                                                           java.lang.String text,
                                                           int maxNumFragments)
                                                    throws java.io.IOException,
                                                           InvalidTokenOffsetsException

      Highlights chosen terms in a text, extracting the most relevant sections. This is a convenience method that calls `getBestFragments(TokenStream, String, int)`
      Parameters:
        `analyzer` - the analyzer that will be used to split `text` into chunks
        `fieldName` - the name of the field being highlighted (used by analyzer)
        `text` - text to highlight terms in
        `maxNumFragments` - the maximum number of fragments.
      Returns:
        highlighted text fragments (between 0 and maxNumFragments number of fragments)
      Throws:
        `InvalidTokenOffsetsException` - thrown if any token's endOffset exceeds the provided text's length
        `java.io.IOException`

    - #### getBestFragments

          public final java.lang.String[] getBestFragments(TokenStream tokenStream,
                                                           java.lang.String text,
                                                           int maxNumFragments)
                                                    throws java.io.IOException,
                                                           InvalidTokenOffsetsException

      Highlights chosen terms in a text, extracting the most relevant sections. The document text is analysed in chunks to record hit statistics across the document. After accumulating stats, the fragments with the highest scores are returned as an array of strings in order of score (contiguous fragments are merged into one in their original order to improve readability)
      Parameters:
        `text` - text to highlight terms in
        `maxNumFragments` - the maximum number of fragments.
      Returns:
        highlighted text fragments (between 0 and maxNumFragments number of fragments)
      Throws:
        `InvalidTokenOffsetsException` - thrown if any token's endOffset exceeds the provided text's length
        `java.io.IOException`

    - #### getBestTextFragments

          public final TextFragment[] getBestTextFragments(TokenStream tokenStream,
                                                           java.lang.String text,
                                                           boolean mergeContiguousFragments,
                                                           int maxNumFragments)
                                                    throws java.io.IOException,
                                                           InvalidTokenOffsetsException

      Low level api to get the most relevant (formatted) sections of the document. This method has been made public to allow visibility of score information held in TextFragment objects. Thanks to Jason Calabrese for help in redefining the interface.
      Parameters:
        `tokenStream` -
        `text` -
        `maxNumFragments` -
        `mergeContiguousFragments` -
      Throws:
        `java.io.IOException`
        `InvalidTokenOffsetsException` - thrown if any token's endOffset exceeds the provided text's length

    - #### getBestFragments

          public final java.lang.String getBestFragments(TokenStream tokenStream,
                                                         java.lang.String text,
                                                         int maxNumFragments,
                                                         java.lang.String separator)
                                                  throws java.io.IOException,
                                                         InvalidTokenOffsetsException

      Highlights terms in the text , extracting the most relevant sections and concatenating the chosen fragments with a separator (typically "..."). The document text is analysed in chunks to record hit statistics across the document. After accumulating stats, the fragments with the highest scores are returned in order as "separator" delimited strings.
      Parameters:
        `text` - text to highlight terms in
        `maxNumFragments` - the maximum number of fragments.
        `separator` - the separator used to intersperse the document fragments (typically "...")
      Returns:
        highlighted text
      Throws:
        `InvalidTokenOffsetsException` - thrown if any token's endOffset exceeds the provided text's length
        `java.io.IOException`

    - #### getMaxDocBytesToAnalyze

          public int getMaxDocBytesToAnalyze()

      Deprecated. See `getMaxDocCharsToAnalyze()`, since this value has always counted on chars. They both set the same internal value, however
      Returns:
        the maximum number of bytes to be tokenized per doc

    - #### setMaxDocBytesToAnalyze

          public void setMaxDocBytesToAnalyze(int byteCount)

      Deprecated. See `setMaxDocCharsToAnalyze(int)`, since this value has always counted chars
      Parameters:
        `byteCount` - the maximum number of bytes to be tokenized per doc (This can improve performance with large documents)

    - #### getMaxDocCharsToAnalyze

          public int getMaxDocCharsToAnalyze()

    - #### setMaxDocCharsToAnalyze

          public void setMaxDocCharsToAnalyze(int maxDocCharsToAnalyze)

    - #### getTextFragmenter

          public Fragmenter getTextFragmenter()

    - #### setTextFragmenter

          public void setTextFragmenter(Fragmenter fragmenter)

      Parameters:
        `fragmenter` -

    - #### getFragmentScorer

          public Scorer getFragmentScorer()

      Returns:
        Object used to score each text fragment

    - #### setFragmentScorer

          public void setFragmentScorer(Scorer scorer)

      Parameters:
        `scorer` -

    - #### getEncoder

          public Encoder getEncoder()

    - #### setEncoder

          public void setEncoder(Encoder encoder)

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