beagled/Lucene.Net/Search/Scorer.cs

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