org.apache.lucene.search
Class Scorer

java.lang.Object
  extended by org.apache.lucene.search.DocIdSetIterator
      extended by org.apache.lucene.search.Scorer
Direct Known Subclasses:
ConstantScoreQuery.ConstantScorer, ScoreCachingWrappingScorer, SpanScorer

public abstract class Scorer
extends DocIdSetIterator

Expert: Common scoring functionality for different types of queries.

A Scorer iterates over documents matching a query in increasing order of doc Id.

Document scores are computed using a given Similarity implementation.

NOTE: The values Float.Nan, Float.NEGATIVE_INFINITY and Float.POSITIVE_INFINITY are not valid scores. Certain collectors (eg TopScoreDocCollector) will not properly collect hits with these scores.


Nested Class Summary
static class Scorer.ScorerVisitor<P extends Query,C extends Query,S extends Scorer>
          A callback to gather information from a scorer and its sub-scorers.
 
Field Summary
protected  Weight weight
           
 
Fields inherited from class org.apache.lucene.search.DocIdSetIterator
NO_MORE_DOCS
 
Constructor Summary
protected Scorer(Similarity similarity)
          Deprecated. Use Scorer(Weight) instead.
protected Scorer(Similarity similarity, Weight weight)
          Deprecated. Use Scorer(Weight) instead.
protected Scorer(Weight weight)
          Constructs a Scorer
 
Method Summary
 float freq()
          Returns number of matches for the current document.
 Similarity getSimilarity()
          Deprecated. Store any Similarity you might need privately in your implementation instead.
abstract  float score()
          Returns the score of the current document matching the query.
 void score(Collector collector)
          Scores and collects all matching documents.
protected  boolean score(Collector collector, int max, int firstDocID)
          Expert: Collects matching documents in a range.
 void visitScorers(Scorer.ScorerVisitor<Query,Query,Scorer> visitor)
          Expert: call this to gather details for all sub-scorers for this query.
protected  void visitSubScorers(Query parent, BooleanClause.Occur relationship, Scorer.ScorerVisitor<Query,Query,Scorer> visitor)
          Scorer subclasses should implement this method if the subclass itself contains multiple scorers to support gathering details for sub-scorers via Scorer.ScorerVisitor
 
Methods inherited from class org.apache.lucene.search.DocIdSetIterator
advance, docID, nextDoc
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

weight

protected final Weight weight
Constructor Detail

Scorer

protected Scorer(Weight weight)
Constructs a Scorer

Parameters:
weight - The scorers Weight.

Scorer

@Deprecated
protected Scorer(Similarity similarity)
Deprecated. Use Scorer(Weight) instead.

Constructs a Scorer.

Parameters:
similarity - The Similarity implementation used by this scorer.

Scorer

@Deprecated
protected Scorer(Similarity similarity,
                            Weight weight)
Deprecated. Use Scorer(Weight) instead.

Constructs a Scorer

Parameters:
similarity - The Similarity implementation used by this scorer.
weight - The scorers Weight
Method Detail

getSimilarity

@Deprecated
public Similarity getSimilarity()
Deprecated. Store any Similarity you might need privately in your implementation instead.

Returns the Similarity implementation used by this scorer.


score

public void score(Collector collector)
           throws IOException
Scores and collects all matching documents.

Parameters:
collector - The collector to which all matching documents are passed.
Throws:
IOException

score

protected boolean score(Collector collector,
                        int max,
                        int firstDocID)
                 throws IOException
Expert: Collects matching documents in a range. Hook for optimization. Note, firstDocID is added to ensure that DocIdSetIterator.nextDoc() was called before this method.

NOTE: Because of backwards compatibility, this method is still declared as protected, but it is intended to be public, because it's called from other classes (like BooleanScorer). If you subclass Scorer, you should declare the overridden method as public to ease transition to Lucene 4.0, where it will be public.

Parameters:
collector - The collector to which all matching documents are passed.
max - Do not score documents past this.
firstDocID - The first document ID (ensures DocIdSetIterator.nextDoc() is called before this method.
Returns:
true if more matching documents may remain.
Throws:
IOException

score

public abstract float score()
                     throws IOException
Returns the score of the current document matching the query. Initially invalid, until DocIdSetIterator.nextDoc() or DocIdSetIterator.advance(int) is called the first time, or when called from within Collector.collect(int).

Throws:
IOException

freq

public float freq()
           throws IOException
Returns number of matches for the current document. This returns a float (not int) because SloppyPhraseScorer discounts its freq according to how "sloppy" the match was.

Throws:
IOException
WARNING: This API is experimental and might change in incompatible ways in the next release.

visitScorers

public void visitScorers(Scorer.ScorerVisitor<Query,Query,Scorer> visitor)
Expert: call this to gather details for all sub-scorers for this query. This can be used, in conjunction with a custom Collector to gather details about how each sub-query matched the current hit.

Parameters:
visitor - a callback executed for each sub-scorer
WARNING: This API is experimental and might change in incompatible ways in the next release.

visitSubScorers

protected void visitSubScorers(Query parent,
                               BooleanClause.Occur relationship,
                               Scorer.ScorerVisitor<Query,Query,Scorer> visitor)
Scorer subclasses should implement this method if the subclass itself contains multiple scorers to support gathering details for sub-scorers via Scorer.ScorerVisitor

Note: this method will throw UnsupportedOperationException if no associated Weight instance is provided to Scorer(Weight)

WARNING: This API is experimental and might change in incompatible ways in the next release.