Package org.apache.lucene.search

# Class TwoPhaseIterator

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

Direct Known Subclasses:
  `DocValuesRangeIterator`

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

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
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 Details

### approximation

protected final DocIdSetIterator approximation

## Constructor Details

### TwoPhaseIterator

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

## Method Details

### 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.