Scorer


1   package org.apache.lucene.search;
2   
3   /**
4    * Copyright 2004 The Apache Software Foundation
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.io.IOException  ;
20  
21  /** Expert: Common scoring functionality for different types of queries.
22   * <br>A <code>Scorer</code> either iterates over documents matching a query,
23   * or provides an explanation of the score for a query for a given document.
24   * <br>Document scores are computed using a given <code>Similarity</code> implementation.
25   */
26  public abstract class Scorer {
27    private Similarity similarity;
28  
29    /** Constructs a Scorer.
30     * @param similarity The <code>Similarity</code> implementation used by this scorer.
31     */
32    protected Scorer(Similarity similarity) {
33      this.similarity = similarity;
34    }
35  
36    /** Returns the Similarity implementation used by this scorer. */
37    public Similarity getSimilarity() {
38      return this.similarity;
39    }
40  
41    /** Scores and collects all matching documents.
42     * @param hc The collector to which all matching documents are passed through
43     * {@link HitCollector#collect(int, float)}.
44     * <br>When this method is used the {@link #explain(int)} method should not be used.
45     */
46    public void score(HitCollector hc) throws IOException   {
47      while (next()) {
48        hc.collect(doc(), score());
49      }
50    }
51  
52    /** Expert: Collects matching documents in a range.  Hook for optimization.
53     * Note that {@link #next()} must be called once before this method is called
54     * for the first time.
55     * @param hc The collector to which all matching documents are passed through
56     * {@link HitCollector#collect(int, float)}.
57     * @param max Do not score documents past this.
58     * @return true if more matching documents may remain.
59     */
60    protected boolean score(HitCollector hc, int max) throws IOException   {
61      while (doc() < max) {
62        hc.collect(doc(), score());
63        if (!next())
64          return false;
65      }
66      return true;
67    }
68  
69    /** Advances to the next document matching the query.
70     * @return true iff there is another document matching the query.
71     * <br>When this method is used the {@link #explain(int)} method should not be used.
72     */
73    public abstract boolean next() throws IOException  ;
74  
75    /** Returns the current document number matching the query.
76     * Initially invalid, until {@link #next()} is called the first time.
77     */
78    public abstract int doc();
79  
80    /** Returns the score of the current document matching the query.
81     * Initially invalid, until {@link #next()} or {@link #skipTo(int)}
82     * is called the first time.
83     */
84    public abstract float score() throws IOException  ;
85  
86    /** Skips to the first match beyond the current whose document number is
87     * greater than or equal to a given target.
88     * <br>When this method is used the {@link #explain(int)} method should not be used.
89     * @param target The target document number.
90     * @return true iff there is such a match.
91     * <p>Behaves as if written: <pre>
92     *   boolean skipTo(int target) {
93     *     do {
94     *       if (!next())
95     *         return false;
96     *     } while (target > doc());
97     *     return true;
98     *   }
99     * </pre>Most implementations are considerably more efficient than that.
100    */
101   public abstract boolean skipTo(int target) throws IOException  ;
102 
103   /** Returns an explanation of the score for a document.
104    * <br>When this method is used, the {@link #next()}, {@link #skipTo(int)} and
105    * {@link #score(HitCollector)} methods should not be used.
106    * @param doc The document number for the explanation.
107    */
108   public abstract Explanation explain(int doc) throws IOException  ;
109 
110 }
111
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags