public interface DocumentIterator
Warning: from MG4J 5.0, this class does not implement
IntIterator. Moreover, {nextDocument() no longer returns -1
to denote end of iteration, but rather END_OF_LIST.
Each call to nextDocument()
will return a document pointer, or END_OF_LIST if no more documents are available. Just
after the call to nextDocument(), intervalIterator(Index) will return an interval iterator
enumerating intervals in the last returned document for the specified index. The latter method may return, as a special result, a
special TRUE value: this means that
albeit the current document satisfies the query, there is only a generic
empty witness to prove it (see TRUE for some elaboration).
A document iterator is usually structured as composite,
with operators as internal nodes and IndexIterators
as leaves. The methods accept(DocumentIteratorVisitor)
and acceptOnTruePaths(DocumentIteratorVisitor) implement the visitor pattern.
The dispose() method is intended to recursively release all resources associated
to a composite document iterator. Note that this is not always what you want, as you might
be, say, pooling index readers to reduce the number
of file open/close operations. For this reason, we intentionally avoid calling the method “close”.
Warning: interval enumeration can be carried out only just after a call
to nextDocument(). Subsequent calls to nextDocument()
will reset the internal state of the iterator.
| Modifier and Type | Field and Description |
|---|---|
static int |
END_OF_LIST
A special value denoting that the end of the list has been reached.
|
| Modifier and Type | Method and Description |
|---|---|
<T> T |
accept(DocumentIteratorVisitor<T> visitor)
Accepts a visitor.
|
<T> T |
acceptOnTruePaths(DocumentIteratorVisitor<T> visitor)
Accepts a visitor after a call to
nextDocument(),
limiting recursion to true paths. |
void |
dispose()
Disposes this document iterator, releasing all resources.
|
int |
document()
Returns the last document returned by
nextDocument(). |
ReferenceSet<Index> |
indices()
Returns the set of indices over which this iterator is built.
|
IntervalIterator |
intervalIterator()
Returns the interval iterator of this document iterator for single-index queries.
|
IntervalIterator |
intervalIterator(Index index)
Returns the interval iterator of this document iterator for the given index.
|
Reference2ReferenceMap<Index,IntervalIterator> |
intervalIterators()
Returns an unmodifiable map from indices to interval iterators.
|
boolean |
mayHaveNext()
Returns whether there may be a next document, possibly with false positives.
|
int |
nextDocument()
Returns the next document provided by this document iterator, or
END_OF_LIST if no more documents are available. |
int |
skipTo(int n)
Skips all documents smaller than
n. |
double |
weight()
Returns the weight associated with this iterator.
|
DocumentIterator |
weight(double weight)
Sets the weight of this index iterator.
|
static final int END_OF_LIST
IntervalIterator intervalIterator() throws IOException
This is a commodity method that can be used only for queries built over a single index.
IllegalStateException - if this document iterator is not built on a single index.IOExceptionintervalIterator(Index)IntervalIterator intervalIterator(Index index) throws IOException
After a call to nextDocument(), this iterator
can be used to retrieve the intervals in the current document (the
one returned by nextDocument()) for
the index index.
Note that if all indices have positions, it is guaranteed that at least one index will return an interval. However, for disjunctive queries it cannot be guaranteed that all indices will return an interval.
Indices without positions always return IntervalIterators.TRUE.
Thus, in presence of indices without positions it is possible that no
intervals at all are available.
index - an index (must be one over which the query was built).index.IOExceptionReference2ReferenceMap<Index,IntervalIterator> intervalIterators() throws IOException
After a call to nextDocument(), this map
can be used to retrieve the intervals in the current document. An invocation of Map.get(java.lang.Object)
on this map with argument index yields the same result as
intervalIterator(index).
UnsupportedOperationException - if this index does not contain positions.IOExceptionintervalIterator(Index)ReferenceSet<Index> indices()
int nextDocument()
throws IOException
END_OF_LIST if no more documents are available.END_OF_LIST if no more documents are available.IOExceptionboolean mayHaveNext()
int document()
nextDocument().nextDocument(), -1 if no document has been returned yet, and
END_OF_LIST if the list of results has been exhausted.int skipTo(int n)
throws IOException
n.
Define the current document k associated with this document iterator
as follows:
nextDocument() and this method have never been called;
END_OF_LIST, if a call to this method or to
nextDocument() returned END_OF_LIST;
nextDocument() or this method, otherwise.
If k is larger than or equal to n, then
this method does nothing and returns k. Otherwise, a
call to this method is equivalent to
while( ( k = nextDocument() ) < n ); return k;
Thus, when a result k ≠ END_OF_LIST
is returned, the state of this iterator
will be exactly the same as after a call to nextDocument()
that returned k.
In particular, the first document larger than or equal to n (when returned
by this method) will not be returned by the next call to
nextDocument().
n - a document pointer.n if available, END_OF_LIST
otherwise.IOException<T> T accept(DocumentIteratorVisitor<T> visitor) throws IOException
A document iterator is usually structured as composite,
with operators as internal nodes and IndexIterators
as leaves. This method implements the visitor pattern.
visitor - the visitor.null if the visit was interrupted.IOException<T> T acceptOnTruePaths(DocumentIteratorVisitor<T> visitor) throws IOException
nextDocument(),
limiting recursion to true paths.
After a call to nextDocument(), a document iterator
is positioned over a document. This call is equivalent to accept(DocumentIteratorVisitor),
but visits only along true paths.
We define a true path as a path from the root of the composite that passes only through
nodes whose associated subtree is positioned on the same document of the root. Note that OrDocumentIterators
detach exhausted iterators from the composite tree, so true paths define the subtree that is causing
the current document to satisfy the query represented by this document iterator.
For more elaboration, and the main application of this method, see CounterCollectionVisitor.
visitor - the visitor.null if the visit was interrupted.IOExceptionaccept(DocumentIteratorVisitor),
CounterCollectionVisitordouble weight()
The number returned by this method has no fixed semantics: different scorers might choose different interpretations, or even ignore it.
DocumentIterator weight(double weight)
weight - the weight of this index iterator.void dispose()
throws IOException
This method should propagate down to the underlying index iterators, where it should release resources such as open files and network connections. If you're doing your own resource tracking and pooling, then you do not need to call this method.
IOException