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
`protected DocIdSetIterator` `approximation`

### Constructor Summary

Constructors
`protected` `TwoPhaseIterator(DocIdSetIterator approximation)` Takes the approximation to be returned by `approximation`.

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`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.