Package 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	Description
protected 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 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.