001: package org.apache.lucene.search;
002:
003: /**
004: * Licensed to the Apache Software Foundation (ASF) under one or more
005: * contributor license agreements. See the NOTICE file distributed with
006: * this work for additional information regarding copyright ownership.
007: * The ASF licenses this file to You under the Apache License, Version 2.0
008: * (the "License"); you may not use this file except in compliance with
009: * the License. You may obtain a copy of the License at
010: *
011: * http://www.apache.org/licenses/LICENSE-2.0
012: *
013: * Unless required by applicable law or agreed to in writing, software
014: * distributed under the License is distributed on an "AS IS" BASIS,
015: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: * See the License for the specific language governing permissions and
017: * limitations under the License.
018: */
019:
020: import java.io.IOException;
021:
022: /**
023: * Expert: Common scoring functionality for different types of queries.
024: *
025: * <p>
026: * A <code>Scorer</code> either iterates over documents matching a
027: * query in increasing order of doc Id, or provides an explanation of
028: * the score for a query for a given document.
029: * </p>
030: * <p>
031: * Document scores are computed using a given <code>Similarity</code>
032: * implementation.
033: * </p>
034: * @see BooleanQuery#setAllowDocsOutOfOrder
035: */
036: public abstract class Scorer {
037: private Similarity similarity;
038:
039: /** Constructs a Scorer.
040: * @param similarity The <code>Similarity</code> implementation used by this scorer.
041: */
042: protected Scorer(Similarity similarity) {
043: this .similarity = similarity;
044: }
045:
046: /** Returns the Similarity implementation used by this scorer. */
047: public Similarity getSimilarity() {
048: return this .similarity;
049: }
050:
051: /** Scores and collects all matching documents.
052: * @param hc The collector to which all matching documents are passed through
053: * {@link HitCollector#collect(int, float)}.
054: * <br>When this method is used the {@link #explain(int)} method should not be used.
055: */
056: public void score(HitCollector hc) throws IOException {
057: while (next()) {
058: hc.collect(doc(), score());
059: }
060: }
061:
062: /** Expert: Collects matching documents in a range. Hook for optimization.
063: * Note that {@link #next()} must be called once before this method is called
064: * for the first time.
065: * @param hc The collector to which all matching documents are passed through
066: * {@link HitCollector#collect(int, float)}.
067: * @param max Do not score documents past this.
068: * @return true if more matching documents may remain.
069: */
070: protected boolean score(HitCollector hc, int max)
071: throws IOException {
072: while (doc() < max) {
073: hc.collect(doc(), score());
074: if (!next())
075: return false;
076: }
077: return true;
078: }
079:
080: /**
081: * Advances to the document matching this Scorer with the lowest doc Id
082: * greater than the current value of {@link #doc()} (or to the matching
083: * document with the lowest doc Id if next has never been called on
084: * this Scorer).
085: *
086: * <p>
087: * When this method is used the {@link #explain(int)} method should not
088: * be used.
089: * </p>
090: *
091: * @return true iff there is another document matching the query.
092: * @see BooleanQuery#setAllowDocsOutOfOrder
093: */
094: public abstract boolean next() throws IOException;
095:
096: /** Returns the current document number matching the query.
097: * Initially invalid, until {@link #next()} is called the first time.
098: */
099: public abstract int doc();
100:
101: /** Returns the score of the current document matching the query.
102: * Initially invalid, until {@link #next()} or {@link #skipTo(int)}
103: * is called the first time.
104: */
105: public abstract float score() throws IOException;
106:
107: /**
108: * Skips to the document matching this Scorer with the lowest doc Id
109: * greater than or equal to a given target.
110: *
111: * <p>
112: * The behavior of this method is undefined if the target specified is
113: * less than or equal to the current value of {@link #doc()}.
114: * <p>
115: * Behaves as if written:
116: * <pre>
117: * boolean skipTo(int target) {
118: * do {
119: * if (!next())
120: * return false;
121: * } while (target > doc());
122: * return true;
123: * }
124: * </pre>
125: * Most implementations are considerably more efficient than that.
126: * </p>
127: *
128: * <p>
129: * When this method is used the {@link #explain(int)} method should not
130: * be used.
131: * </p>
132: *
133: * @param target The target document number.
134: * @return true iff there is such a match.
135: * @see BooleanQuery#setAllowDocsOutOfOrder
136: */
137: public abstract boolean skipTo(int target) throws IOException;
138:
139: /** Returns an explanation of the score for a document.
140: * <br>When this method is used, the {@link #next()}, {@link #skipTo(int)} and
141: * {@link #score(HitCollector)} methods should not be used.
142: * @param doc The document number for the explanation.
143: */
144: public abstract Explanation explain(int doc) throws IOException;
145:
146: }
|