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.
int	docIDRunEnd()	Returns the end of the run of consecutive doc IDs that match this TwoPhaseIterator and that contains the current doc ID of the approximation, that is: one plus the last doc ID of the run.
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.

docIDRunEnd

public int docIDRunEnd()
                throws IOException

Returns the end of the run of consecutive doc IDs that match this TwoPhaseIterator and that contains the current doc ID of the approximation, that is: one plus the last doc ID of the run.

Note: It is illegal to call this method when the approximation is exhausted or not positioned.

The default implementation returns the current doc ID of the approximation.

Throws:

IOException