Home » lucene-3.0.1-src » org.apache » lucene » search » function » [javadoc | source]

    1   package org.apache.lucene.search.function;
    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   import org.apache.lucene.index.IndexReader;
   23   import org.apache.lucene.search.ComplexExplanation;
   24   import org.apache.lucene.search.Explanation;
   25   import org.apache.lucene.search.FieldCache; // for javadocs
   26   
   27   /**
   28    * An instance of this subclass should be returned by
   29    * {@link CustomScoreQuery#getCustomScoreProvider}, if you want
   30    * to modify the custom score calculation of a {@link CustomScoreQuery}.
   31    * <p>Since Lucene 2.9, queries operate on each segment of an Index separately,
   32    * so overriding the similar (now deprecated) methods in {@link CustomScoreQuery}
   33    * is no longer suitable, as the supplied <code>doc</code> ID is per-segment
   34    * and without knowledge of the IndexReader you cannot access the
   35    * document or {@link FieldCache}.
   36    * 
   37    * @lucene.experimental
   38    * @since 2.9.2
   39    */
   40   public class CustomScoreProvider {
   41   
   42     protected final IndexReader reader;
   43   
   44     /**
   45      * Creates a new instance of the provider class for the given {@link IndexReader}.
   46      */
   47     public CustomScoreProvider(IndexReader reader) {
   48       this.reader = reader;
   49     }
   50   
   51     /**
   52      * Compute a custom score by the subQuery score and a number of 
   53      * {@link ValueSourceQuery} scores.
   54      * <p> 
   55      * Subclasses can override this method to modify the custom score.  
   56      * <p>
   57      * If your custom scoring is different than the default herein you 
   58      * should override at least one of the two customScore() methods.
   59      * If the number of ValueSourceQueries is always &lt; 2 it is 
   60      * sufficient to override the other 
   61      * {@link #customScore(int, float, float) customScore()} 
   62      * method, which is simpler. 
   63      * <p>
   64      * The default computation herein is a multiplication of given scores:
   65      * <pre>
   66      *     ModifiedScore = valSrcScore * valSrcScores[0] * valSrcScores[1] * ...
   67      * </pre>
   68      * 
   69      * @param doc id of scored doc. 
   70      * @param subQueryScore score of that doc by the subQuery.
   71      * @param valSrcScores scores of that doc by the ValueSourceQuery.
   72      * @return custom score.
   73      */
   74     public float customScore(int doc, float subQueryScore, float valSrcScores[]) throws IOException {
   75       if (valSrcScores.length == 1) {
   76         return customScore(doc, subQueryScore, valSrcScores[0]);
   77       }
   78       if (valSrcScores.length == 0) {
   79         return customScore(doc, subQueryScore, 1);
   80       }
   81       float score = subQueryScore;
   82       for(int i = 0; i < valSrcScores.length; i++) {
   83         score *= valSrcScores[i];
   84       }
   85       return score;
   86     }
   87   
   88     /**
   89      * Compute a custom score by the subQuery score and the ValueSourceQuery score.
   90      * <p> 
   91      * Subclasses can override this method to modify the custom score.
   92      * <p>
   93      * If your custom scoring is different than the default herein you 
   94      * should override at least one of the two customScore() methods.
   95      * If the number of ValueSourceQueries is always &lt; 2 it is 
   96      * sufficient to override this customScore() method, which is simpler. 
   97      * <p>
   98      * The default computation herein is a multiplication of the two scores:
   99      * <pre>
  100      *     ModifiedScore = subQueryScore * valSrcScore
  101      * </pre>
  102      *
  103      * @param doc id of scored doc. 
  104      * @param subQueryScore score of that doc by the subQuery.
  105      * @param valSrcScore score of that doc by the ValueSourceQuery.
  106      * @return custom score.
  107      */
  108     public float customScore(int doc, float subQueryScore, float valSrcScore) throws IOException {
  109       return subQueryScore * valSrcScore;
  110     }
  111   
  112     /**
  113      * Explain the custom score.
  114      * Whenever overriding {@link #customScore(int, float, float[])}, 
  115      * this method should also be overridden to provide the correct explanation
  116      * for the part of the custom scoring.
  117      *  
  118      * @param doc doc being explained.
  119      * @param subQueryExpl explanation for the sub-query part.
  120      * @param valSrcExpls explanation for the value source part.
  121      * @return an explanation for the custom score
  122      */
  123     public Explanation customExplain(int doc, Explanation subQueryExpl, Explanation valSrcExpls[]) throws IOException {
  124       if (valSrcExpls.length == 1) {
  125         return customExplain(doc, subQueryExpl, valSrcExpls[0]);
  126       }
  127       if (valSrcExpls.length == 0) {
  128         return subQueryExpl;
  129       }
  130       float valSrcScore = 1;
  131       for (int i = 0; i < valSrcExpls.length; i++) {
  132         valSrcScore *= valSrcExpls[i].getValue();
  133       }
  134       Explanation exp = new Explanation( valSrcScore * subQueryExpl.getValue(), "custom score: product of:");
  135       exp.addDetail(subQueryExpl);
  136       for (int i = 0; i < valSrcExpls.length; i++) {
  137         exp.addDetail(valSrcExpls[i]);
  138       }
  139       return exp;
  140     }
  141     
  142     /**
  143      * Explain the custom score.
  144      * Whenever overriding {@link #customScore(int, float, float)}, 
  145      * this method should also be overridden to provide the correct explanation
  146      * for the part of the custom scoring.
  147      *  
  148      * @param doc doc being explained.
  149      * @param subQueryExpl explanation for the sub-query part.
  150      * @param valSrcExpl explanation for the value source part.
  151      * @return an explanation for the custom score
  152      */
  153     public Explanation customExplain(int doc, Explanation subQueryExpl, Explanation valSrcExpl) throws IOException {
  154       float valSrcScore = 1;
  155       if (valSrcExpl != null) {
  156         valSrcScore *= valSrcExpl.getValue();
  157       }
  158       Explanation exp = new Explanation( valSrcScore * subQueryExpl.getValue(), "custom score: product of:");
  159       exp.addDetail(subQueryExpl);
  160       exp.addDetail(valSrcExpl);
  161       return exp;
  162     }
  163   
  164   }

Home » lucene-3.0.1-src » org.apache » lucene » search » function » [javadoc | source]