it.unimi.di.mg4j.search.visitor
Interface DocumentIteratorVisitor<T>

All Known Implementing Classes:

AbstractDocumentIteratorVisitor, BM25FScorer.Visitor, CounterCollectionVisitor, CounterSetupVisitor, TermCollectionVisitor, TrueTermsCollectionVisitor

public interface DocumentIteratorVisitor<T>

A visitor for the tree defined by a DocumentIterator.

Implementations of this interface must be reusable. The user must invoke prepare() before a visit so that the internal state of the visitor can be suitably set up.

Document-iterator visitors can optionally return values. In this case, the newArray(int) method must be properly implemented. Otherwise, it can safely return null: all implementations of DocumentIterator.accept(DocumentIteratorVisitor) and DocumentIterator.acceptOnTruePaths(DocumentIteratorVisitor) must be prepared for this to happen. (It would be of course possible to pass around empty arrays, but visitors on document iterators usually have performance issues.)

If a document-iterator visitor does not return values, it is suggested that it is parameterised on Boolean and that it returns Boolean.TRUE to denote that a visit should not end.

For maximum flexibility, there is just one type of visit method for leaves, but two visits methods for internal nodes, which should be used for preorder and postorder visits, respectively.

The visit methods for leaves are actually two, as they depend on the visited leaf (more precisely, whether it is an IndexIterator or a MultiTermIndexIterator. The reason for this choice is that in some cases the term-like nature of a MultiTermIndexIterator makes it easier to write scorers that don't know about expansions (e.g., BM25Scorer. On the other hand, some scorers might want to delve into a MultiTermIndexIterator and discover using MultiTermIndexIterator.front(IndexIterator[]) which terms where actually found. The visit(MultiTermIndexIterator) makes this goal easily reachable.

Note that this visitor interface and that defined in QueryBuilderVisitor are based on different principles: in the latter case, the action of the visitor will likely be different for each type of internal node, so we have specific visit methods for each type of such nodes. In our case, the visit will most likely behave differently just for internal nodes and leaves, so we prefer a simpler interface that also let us implement more easily visitor acceptance methods (DocumentIterator.accept(DocumentIteratorVisitor) and DocumentIterator.acceptOnTruePaths(DocumentIteratorVisitor)).

Author:

Sebastiano Vigna

Method Summary

T[]	newArray(int len) Builds an array of given length of type T.
DocumentIteratorVisitor<T>	prepare() Prepares the internal state of this visitor for a(nother) visit.
T	visit(FalseDocumentIterator falseDocumentIterator) Visits a FalseDocumentIterator leaf.
T	visit(IndexIterator indexIterator) Visits an IndexIterator leaf.
T	visit(MultiTermIndexIterator multiTermIndexIterator) Visits a MultiTermIndexIterator leaf.
T	visit(TrueDocumentIterator trueDocumentIterator) Visits a TrueDocumentIterator leaf.
T	visitPost(DocumentIterator documentIterator, T[] subNodeResult) Visits an internal node after recursing into the corresponding subtree.
boolean	visitPre(DocumentIterator documentIterator) Visits an internal node before recursing into the corresponding subtree.

Method Detail

prepare

DocumentIteratorVisitor<T> prepare()

Prepares the internal state of this visitor for a(nother) visit.

By specification, it must be safe to call this method any number of times.

Returns:

this visitor.

newArray

T[] newArray(int len)

Builds an array of given length of type T.

Because of erasure, generic classes in Java cannot allocate arrays of generic types. This impossibility can be a problem if for some reason the visitPost() methods expect an actual array of type T. This method must provide an array of given length that is an acceptable input for all visitPost() methods.

Note that by declaring an implementing class of this interface that has a sole constructor accepting an argument of type Class<T>, you will force the user to provide the class of the generic type, opening the way for the reflective methods in Array.

Parameters:

len - the required array length.

Returns:

an array of type T of length len, or null if this document iterator visitor does not return values.

visitPre

boolean visitPre(DocumentIterator documentIterator)

Visits an internal node before recursing into the corresponding subtree.

Parameters:

documentIterator - the internal node to be visited.

Returns:

true if the visit should continue.

visitPost

T visitPost(DocumentIterator documentIterator,
            T[] subNodeResult)

Visits an internal node after recursing into the corresponding subtree.

Parameters:

documentIterator - the internal node to be visited.

subNodeResult - the array of results returned by subnodes.

Returns:

an appropriate return value (usually, the object built using the elements in subNode) if the visit should continue, or null.

visit

T visit(IndexIterator indexIterator)
        throws IOException

Visits an IndexIterator leaf.

Parameters:

indexIterator - the leaf to be visited.

Returns:

an appropriate return value if the visit should continue, or null.

Throws:

IOException

visit

T visit(MultiTermIndexIterator multiTermIndexIterator)
        throws IOException

Visits a MultiTermIndexIterator leaf.

Parameters:

multiTermIndexIterator - the leaf to be visited.

Returns:

an appropriate return value if the visit should continue, or null.

Throws:

IOException

visit

T visit(TrueDocumentIterator trueDocumentIterator)
        throws IOException

Visits a TrueDocumentIterator leaf.

Parameters:

trueDocumentIterator - the leaf to be visited.

Returns:

an appropriate return value if the visit should continue, or null.

Throws:

IOException

visit

T visit(FalseDocumentIterator falseDocumentIterator)
        throws IOException

Visits a FalseDocumentIterator leaf.

Parameters:

falseDocumentIterator - the leaf to be visited.

Returns:

an appropriate return value if the visit should continue, or null.

Throws:

IOException