1   package org.apache.lucene.search;
    2   
    3   /**
    4    * Licensed to the Apache Software Foundation (ASF) under one or more
    5    * contributor license agreements.  See the NOTICE file distributed with
    6    * this work for additional information regarding copyright ownership.
    7    * The ASF licenses this file to You under the Apache License, Version 2.0
    8    * (the "License"); you may not use this file except in compliance with
    9    * the License.  You may obtain a copy of the License at
   10    *
   11    *     http://www.apache.org/licenses/LICENSE-2.0
   12    *
   13    * Unless required by applicable law or agreed to in writing, software
   14    * distributed under the License is distributed on an "AS IS" BASIS,
   15    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   16    * See the License for the specific language governing permissions and
   17    * limitations under the License.
   18    */
   19   
   20   import java.io.IOException;
   21   
   22   /**
   23    * Expert: Common scoring functionality for different types of queries.
   24    *
   25    * <p>
   26    * A <code>Scorer</code> iterates over documents matching a
   27    * query in increasing order of doc Id.
   28    * </p>
   29    * <p>
   30    * Document scores are computed using a given <code>Similarity</code>
   31    * implementation.
   32    * </p>
   33    *
   34    * <p><b>NOTE</b>: The values Float.Nan,
   35    * Float.NEGATIVE_INFINITY and Float.POSITIVE_INFINITY are
   36    * not valid scores.  Certain collectors (eg {@link
   37    * TopScoreDocCollector}) will not properly collect hits
   38    * with these scores.
   39    */
   40   public abstract class Scorer extends DocIdSetIterator {
   41     private Similarity similarity;
   42   
   43     /** Constructs a Scorer.
   44      * @param similarity The <code>Similarity</code> implementation used by this scorer.
   45      */
   46     protected Scorer(Similarity similarity) {
   47       this.similarity = similarity;
   48     }
   49   
   50     /** Returns the Similarity implementation used by this scorer. */
   51     public Similarity getSimilarity() {
   52       return this.similarity;
   53     }
   54   
   55     /** Scores and collects all matching documents.
   56      * @param collector The collector to which all matching documents are passed.
   57      */
   58     public void score(Collector collector) throws IOException {
   59       collector.setScorer(this);
   60       int doc;
   61       while ((doc = nextDoc()) != NO_MORE_DOCS) {
   62         collector.collect(doc);
   63       }
   64     }
   65   
   66     /**
   67      * Expert: Collects matching documents in a range. Hook for optimization.
   68      * Note, <code>firstDocID</code> is added to ensure that {@link #nextDoc()}
   69      * was called before this method.
   70      * 
   71      * @param collector
   72      *          The collector to which all matching documents are passed.
   73      * @param max
   74      *          Do not score documents past this.
   75      * @param firstDocID
   76      *          The first document ID (ensures {@link #nextDoc()} is called before
   77      *          this method.
   78      * @return true if more matching documents may remain.
   79      */
   80     protected boolean score(Collector collector, int max, int firstDocID) throws IOException {
   81       collector.setScorer(this);
   82       int doc = firstDocID;
   83       while (doc < max) {
   84         collector.collect(doc);
   85         doc = nextDoc();
   86       }
   87       return doc != NO_MORE_DOCS;
   88     }
   89     
   90     /** Returns the score of the current document matching the query.
   91      * Initially invalid, until {@link #nextDoc()} or {@link #advance(int)}
   92      * is called the first time, or when called from within
   93      * {@link Collector#collect}.
   94      */
   95     public abstract float score() throws IOException;
   96   
   97   }