Package org.apache.lucene.index

# Class TermStates

java.lang.Object
org.apache.lucene.index.TermStates

public final class TermStates extends Object
Maintains a `IndexReader` `TermState` view over `IndexReader` instances containing a single term. The `TermStates` doesn't track if the given `TermState` objects are valid, neither if the `TermState` instances refer to the same terms in the associated readers.

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

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TermStates(IndexReaderContext context)`
  Creates an empty `TermStates` from a `IndexReaderContext`
  `TermStates(IndexReaderContext context, TermState state, int ord, int docFreq, long totalTermFreq)`
  Creates a `TermStates` with an initial `TermState`, `IndexReader` pair.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `accumulateStatistics(int docFreq, long totalTermFreq)`
  Expert: Accumulate term statistics.
  `static TermStates`
  `build(IndexSearcher indexSearcher, Term term, boolean needsStats)`
  Creates a `TermStates` from a top-level `IndexReaderContext` and the given `Term`.
  `void`
  `clear()`
  Clears the `TermStates` internal state and removes all registered `TermState`s
  `int`
  `docFreq()`
  Returns the accumulated document frequency of all `TermState` instances passed to `register(TermState, int, int, long)`.
  `IOSupplier<TermState>`
  `get(LeafReaderContext ctx)`
  Returns a `Supplier` for a `TermState` for the given `LeafReaderContext`.
  `void`
  `register(TermState state, int ord)`
  Expert: Registers and associates a `TermState` with an leaf ordinal.
  `void`
  `register(TermState state, int ord, int docFreq, long totalTermFreq)`
  Registers and associates a `TermState` with an leaf ordinal.
  `String`
  `toString()`
  `long`
  `totalTermFreq()`
  Returns the accumulated term frequency of all `TermState` instances passed to `register(TermState, int, int, long)`.
  `boolean`
  `wasBuiltFor(IndexReaderContext context)`
  Expert: Return whether this `TermStates` was built for the given `IndexReaderContext`.

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

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

- ## Constructor Details

  - ### TermStates

    public TermStates(IndexReaderContext context)
    Creates an empty `TermStates` from a `IndexReaderContext`

  - ### TermStates

    public TermStates(IndexReaderContext context, TermState state, int ord, int docFreq, long totalTermFreq)
    Creates a `TermStates` with an initial `TermState`, `IndexReader` pair.

- ## Method Details

  - ### wasBuiltFor

    public boolean wasBuiltFor(IndexReaderContext context)
    Expert: Return whether this `TermStates` was built for the given `IndexReaderContext`. This is typically used for assertions.
    NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

  - ### build

    public static TermStates build(IndexSearcher indexSearcher, Term term, boolean needsStats) throws IOException
    Creates a `TermStates` from a top-level `IndexReaderContext` and the given `Term`. This method will lookup the given term in all context's leaf readers and register each of the readers containing the term in the returned `TermStates` using the leaf reader's ordinal.

    Note: the given context must be a top-level context.

    Parameters:
      `needsStats` - if `true` then all leaf contexts will be visited up-front to collect term statistics. Otherwise, the `TermState` objects will be built only when requested
    Throws:
      `IOException`

  - ### clear

    public void clear()
    Clears the `TermStates` internal state and removes all registered `TermState`s

  - ### register

    public void register(TermState state, int ord, int docFreq, long totalTermFreq)
    Registers and associates a `TermState` with an leaf ordinal. The leaf ordinal should be derived from a `IndexReaderContext`'s leaf ord.

  - ### register

    public void register(TermState state, int ord)
    Expert: Registers and associates a `TermState` with an leaf ordinal. The leaf ordinal should be derived from a `IndexReaderContext`'s leaf ord. On the contrary to `register(TermState, int, int, long)` this method does NOT update term statistics.

  - ### accumulateStatistics

    public void accumulateStatistics(int docFreq, long totalTermFreq)
    Expert: Accumulate term statistics.

  - ### get

    public IOSupplier<TermState> get(LeafReaderContext ctx) throws IOException
    Returns a `Supplier` for a `TermState` for the given `LeafReaderContext`. This may return `null` if some cheap checks help figure out that this term doesn't exist in this leaf. The `Supplier` may then also return `null` if the term doesn't exist.

    Calling this method typically schedules some I/O in the background, so it is recommended to retrieve `Supplier`s across all required terms first before calling `Supplier.get()` on all `Supplier`s so that the I/O for these terms can be performed in parallel.

    Parameters:
      `ctx` - the `LeafReaderContext` to get the `TermState` for.
    Returns:
      a Supplier for a TermState.
    Throws:
      `IOException`

  - ### docFreq

    public int docFreq()
    Returns the accumulated document frequency of all `TermState` instances passed to `register(TermState, int, int, long)`.
    Returns:
      the accumulated document frequency of all `TermState` instances passed to `register(TermState, int, int, long)`.

  - ### totalTermFreq

    public long totalTermFreq()
    Returns the accumulated term frequency of all `TermState` instances passed to `register(TermState, int, int, long)`.
    Returns:
      the accumulated term frequency of all `TermState` instances passed to `register(TermState, int, int, long)`.

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`