org.apache.lucene.search

## Class TwoPhaseIterator

- java.lang.Object
- - org.apache.lucene.search.TwoPhaseIterator

-     public abstract class TwoPhaseIterator
      extends Object

  Returned by `Scorer.twoPhaseIterator()` to expose an approximation of a `DocIdSetIterator`. When the `approximation()`'s `DocIdSetIterator.nextDoc()` or `DocIdSetIterator.advance(int)` return, `matches()` needs to be checked in order to know whether the returned doc ID actually matches.
  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected DocIdSetIterator` | `approximation`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `TwoPhaseIterator(DocIdSetIterator approximation)` Takes the approximation to be returned by `approximation`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `DocIdSetIterator` | `approximation()` Return an approximation.
    `static DocIdSetIterator` | `asDocIdSetIterator(TwoPhaseIterator twoPhaseIterator)` Return a `DocIdSetIterator` view of the provided `TwoPhaseIterator`.
    `abstract float` | `matchCost()` An estimate of the expected cost to determine that a single document `matches()`.
    `abstract boolean` | `matches()` Return whether the current doc ID that `approximation()` is on matches.
    `static TwoPhaseIterator` | `unwrap(DocIdSetIterator iterator)` If the given `DocIdSetIterator` has been created with `asDocIdSetIterator(org.apache.lucene.search.TwoPhaseIterator)`, then this will return the wrapped `TwoPhaseIterator`.

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

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

- - ### Field Detail

    - #### approximation

          protected final DocIdSetIterator approximation

  - ### Constructor Detail

    - #### TwoPhaseIterator

          protected TwoPhaseIterator(DocIdSetIterator approximation)

      Takes the approximation to be returned by `approximation`. Not null.

  - ### Method Detail

    - #### asDocIdSetIterator

          public static DocIdSetIterator asDocIdSetIterator(TwoPhaseIterator twoPhaseIterator)

      Return a `DocIdSetIterator` view of the provided `TwoPhaseIterator`.

    - #### unwrap

          public static TwoPhaseIterator unwrap(DocIdSetIterator iterator)

      If the given `DocIdSetIterator` has been created with `asDocIdSetIterator(org.apache.lucene.search.TwoPhaseIterator)`, then this will return the wrapped `TwoPhaseIterator`. Otherwise this returns `null`.

    - #### approximation

          public DocIdSetIterator approximation()

      Return an approximation. The returned `DocIdSetIterator` is a superset of the matching documents, and each match needs to be confirmed with `matches()` in order to know whether it matches or not.

    - #### matches

          public abstract boolean matches()
                                   throws IOException

      Return whether the current doc ID that `approximation()` is on matches. This method should only be called when the iterator is positioned -- ie. not when `DocIdSetIterator.docID()` is `-1` or `DocIdSetIterator.NO_MORE_DOCS` -- and at most once.
      Throws:
        `IOException`

    - #### matchCost

          public abstract float matchCost()

      An estimate of the expected cost to determine that a single document `matches()`. This can be called before iterating the documents of `approximation()`. Returns an expected cost in number of simple operations like addition, multiplication, comparing two numbers and indexing an array. The returned value must be positive.

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