it.unimi.dsi.mg4j.search
Class AbstractCompositeDocumentIterator

java.lang.Object
  extended by it.unimi.dsi.fastutil.ints.AbstractIntIterator
      extended by it.unimi.dsi.mg4j.search.AbstractDocumentIterator
          extended by it.unimi.dsi.mg4j.search.AbstractCompositeDocumentIterator
All Implemented Interfaces:
IntIterator, DocumentIterator, Iterable<Interval>, Iterator<Integer>
Direct Known Subclasses:
AbstractIntersectionDocumentIterator, AbstractUnionDocumentIterator

public abstract class AbstractCompositeDocumentIterator
extends AbstractDocumentIterator
implements DocumentIterator

An abstract iterator on documents, based on a list of component iterators.

The constructor caches into documentIterator the component iterators, and sets up a number of protected fields that can be useful to implementors. It also provide abstract member classes that make it easier to implement interval iterators.

Note that this class implementa both accept(DocumentIteratorVisitor) and acceptOnTruePaths(DocumentIteratorVisitor) with a series of recursive calls on all component iterator. If you desire a different behaviour for acceptOnTruePaths(DocumentIteratorVisitor) (see, e.g., OrDocumentIterator, please override it.


Nested Class Summary
protected static class AbstractCompositeDocumentIterator.AbstractCompositeIndexIntervalIterator
          An abstract IndexIterator-based interval iterator.
protected static class AbstractCompositeDocumentIterator.AbstractCompositeIntervalIterator
          An abstract interval iterator.
 
Nested classes/interfaces inherited from class it.unimi.dsi.mg4j.search.AbstractDocumentIterator
AbstractDocumentIterator.AbstractIntervalIterator
 
Field Summary
protected  DocumentIterator[] documentIterator
          The component document iterators.
protected  IndexIterator[] indexIterator
          A cached copy of documentIterator, if all underlying iterators are index iterators; null, otherwise.
protected  ReferenceArraySet<Index> indices
          The set of indices involved in this iterator.
protected  int n
          The number of component iterators.
protected  Index soleIndex
          If not null, the sole index involved in this iterator.
 
Fields inherited from class it.unimi.dsi.mg4j.search.AbstractDocumentIterator
last, next
 
Constructor Summary
protected AbstractCompositeDocumentIterator(DocumentIterator... documentIterator)
          Creates a new composite document iterator using a given list of component document iterators.
protected AbstractCompositeDocumentIterator(Index index, DocumentIterator... documentIterator)
          Creates a new composite document iterator using a given list of component document iterators and a specified index.
 
Method Summary
 boolean accept(DocumentIteratorVisitor visitor)
          Accepts a visitor.
 boolean acceptOnTruePaths(DocumentIteratorVisitor visitor)
          Accepts a visitor after a call to DocumentIterator.nextDocument(), limiting recursion to true paths.
 void dispose()
          Disposes this document iterator, releasing all resources.
 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.
 String toString()
           
 
Methods inherited from class it.unimi.dsi.mg4j.search.AbstractDocumentIterator
document, hasNext, iterator, nextInt
 
Methods inherited from class it.unimi.dsi.fastutil.ints.AbstractIntIterator
next, remove, skip
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface it.unimi.dsi.mg4j.search.DocumentIterator
document, intervalIterator, intervalIterators, iterator, nextDocument, nextInt, skipTo
 
Methods inherited from interface it.unimi.dsi.fastutil.ints.IntIterator
skip
 
Methods inherited from interface java.util.Iterator
hasNext, next, remove
 

Field Detail

documentIterator

protected final DocumentIterator[] documentIterator
The component document iterators.


n

protected final int n
The number of component iterators.


indexIterator

protected final IndexIterator[] indexIterator
A cached copy of documentIterator, if all underlying iterators are index iterators; null, otherwise.


indices

protected final ReferenceArraySet<Index> indices
The set of indices involved in this iterator.


soleIndex

protected final Index soleIndex
If not null, the sole index involved in this iterator.

Constructor Detail

AbstractCompositeDocumentIterator

protected AbstractCompositeDocumentIterator(Index index,
                                            DocumentIterator... documentIterator)
Creates a new composite document iterator using a given list of component document iterators and a specified index.

Parameters:
index - an index that will constitute the only index for which this iterator will return intervals, or null to require the computation of the set of indices as the union of the indices of all component iterators.
documentIterator - the component iterators.

AbstractCompositeDocumentIterator

protected AbstractCompositeDocumentIterator(DocumentIterator... documentIterator)
Creates a new composite document iterator using a given list of component document iterators.

Parameters:
documentIterator - the component iterators.
Method Detail

accept

public boolean accept(DocumentIteratorVisitor visitor)
               throws IOException
Description copied from interface: DocumentIterator
Accepts a visitor.

A document iterator is usually structured as composite, with operators as internal nodes and IndexIterators as leaves. This method implements the visitor pattern.

Specified by:
accept in interface DocumentIterator
Parameters:
visitor - the visitor.
Returns:
true if the visit should continue.
Throws:
IOException

acceptOnTruePaths

public boolean acceptOnTruePaths(DocumentIteratorVisitor visitor)
                          throws IOException
Description copied from interface: DocumentIterator
Accepts a visitor after a call to DocumentIterator.nextDocument(), limiting recursion to true paths.

After a call to DocumentIterator.nextDocument(), a document iterator is positioned over a document. This call is equivalent to DocumentIterator.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.

Specified by:
acceptOnTruePaths in interface DocumentIterator
Parameters:
visitor - the visitor.
Returns:
true if the visit should continue.
Throws:
IOException
See Also:
DocumentIterator.accept(DocumentIteratorVisitor), CounterCollectionVisitor

indices

public ReferenceSet<Index> indices()
Description copied from interface: DocumentIterator
Returns the set of indices over which this iterator is built.

Specified by:
indices in interface DocumentIterator
Returns:
the set of indices over which this iterator is built.

intervalIterator

public IntervalIterator intervalIterator()
                                  throws IOException
Description copied from interface: DocumentIterator
Returns the interval iterator of this document iterator for single-index queries.

This is a commodity method that can be used only for queries built over a single index.

Specified by:
intervalIterator in interface DocumentIterator
Returns:
an interval iterator.
Throws:
IOException
See Also:
DocumentIterator.intervalIterator(Index)

dispose

public void dispose()
             throws IOException
Description copied from interface: DocumentIterator
Disposes this document iterator, releasing all resources.

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.

Specified by:
dispose in interface DocumentIterator
Throws:
IOException

toString

public String toString()
Overrides:
toString in class Object