Scorer iterates over all documents matching a query,
+ * or provides an explanation of the score for a query for a given document.
+ * Similarity implementation.
+ */
public abstract class Scorer {
private Similarity similarity;
- /** Constructs a Scorer. */
+ /** Constructs a Scorer.
+ * @param similarity The Similarity implementation used by this scorer.
+ */
protected Scorer(Similarity similarity) {
this.similarity = similarity;
}
@@ -32,28 +38,36 @@
return this.similarity;
}
- /** Scores all documents and passes them to a collector. */
+ /** Scores and collects all matching documents.
+ * @param hc The collector to which all matching documents are passed through
+ * {@link HitCollector#collect(int, float)}.
+ */
public void score(HitCollector hc) throws IOException {
while (next()) {
hc.collect(doc(), score());
}
}
- /** Advance to the next document matching the query. Returns true iff there
- * is another match. */
+ /** Advances to the next document matching the query.
+ * @return true iff there is another document matching the query.
+ */
public abstract boolean next() throws IOException;
- /** Returns the current document number. Initially invalid, until {@link
- * #next()} is called the first time. */
+ /** Returns the current document number matching the query.
+ * Initially invalid, until {@link #next()} is called the first time.
+ */
public abstract int doc();
- /** Returns the score of the current document. Initially invalid, until
- * {@link #next()} is called the first time. */
+ /** Returns the score of the current document matching the query.
+ * Initially invalid, until {@link #next()} is called the first time.
+ */
public abstract float score() throws IOException;
/** Skips to the first match beyond the current whose document number is
- * greater than or equal to target. Returns true iff there is such - * a match.
Behaves as if written:
+ * greater than or equal to a given target. + * @param target The target document number. + * @return true iff there is such a match. + *Behaves as if written:
* boolean skipTo(int target) { * do { * if (!next()) @@ -66,7 +80,11 @@ */ public abstract boolean skipTo(int target) throws IOException; - /** Returns an explanation of the score fordoc. */ + /** Returns an explanation of the score for a document. + *
When this method is used, the {@link #next()} method + * and the {@link #score(HitCollector)} method should not be used. + * @param doc The document number for the explanation. + */ public abstract Explanation explain(int doc) throws IOException; } Index: src/java/org/apache/lucene/search/TermScorer.java =================================================================== RCS file: /home/cvspublic/jakarta-lucene/src/java/org/apache/lucene/search/TermScorer.java,v retrieving revision 1.10 diff -u -r1.10 TermScorer.java --- src/java/org/apache/lucene/search/TermScorer.java 25 Jul 2004 15:10:36 -0000 1.10 +++ src/java/org/apache/lucene/search/TermScorer.java 28 Jul 2004 09:28:42 -0000 @@ -20,6 +20,8 @@ import org.apache.lucene.index.TermDocs; +/** Expert: AScorerfor documents matching aTerm. + */ final class TermScorer extends Scorer { private Weight weight; private TermDocs termDocs; @@ -35,6 +37,12 @@ private static final int SCORE_CACHE_SIZE = 32; private float[] scoreCache = new float[SCORE_CACHE_SIZE]; + /** Construct aTermScorer. + * @param weight The weight of theTermin the query. + * @param td An iterator over the documents matching theTerm. + * @param similarity The Similarity implementation to be used for score computations. + * @param norms The field norms of the document fields for theTerm. + */ TermScorer(Weight weight, TermDocs td, Similarity similarity, byte[] norms) throws IOException { super(similarity); @@ -47,8 +55,16 @@ scoreCache[i] = getSimilarity().tf(i) * weightValue; } + /** Returns the current document number matching the query. + * Initially invalid, until {@link #next()} is called the first time. + */ public int doc() { return doc; } + /** Advances to the next document matching the query. + *
The iterator over the matching documents is buffered using + * {@link TermDocs#read(int[],int[])}. + * @return true iff there is another document matching the query. + */ public boolean next() throws IOException { pointer++; if (pointer >= pointerMax) { @@ -65,6 +81,15 @@ return true; } + /** Returns the score of the current document matching theTerm. + * Initially invalid, until {@link #next()} is called the first time. + * @return The product of: + *
TermScorer. */
public String toString() { return "scorer(" + weight + ")"; }
-
}
Index: src/java/org/apache/lucene/search/Weight.java
===================================================================
RCS file: /home/cvspublic/jakarta-lucene/src/java/org/apache/lucene/search/Weight.java,v
retrieving revision 1.3
diff -u -r1.3 Weight.java
--- src/java/org/apache/lucene/search/Weight.java 29 Mar 2004 22:48:04 -0000 1.3
+++ src/java/org/apache/lucene/search/Weight.java 28 Jul 2004 09:28:42 -0000
@@ -25,7 +25,7 @@
* A Weight is constructed by a query, given a Searcher ({@link * Query#createWeight(Searcher)}). The {@link #sumOfSquaredWeights()} method * is then called on the top-level query to compute the query normalization - * factor (@link Similarity#queryNorm(float)}). This factor is then passed to + * factor {@link Similarity#queryNorm(float)}. This factor is then passed to * {@link #normalize(float)}. At this point the weighting is complete and a * scorer may be constructed by calling {@link #scorer(IndexReader)}. */