Since Lucene 2.9, queries operate on each segment of an index separately,
+ * so the protected {@link #reader} field can be used to resolve doc IDs,
+ * as the supplied doc ID is per-segment and without knowledge
+ * of the IndexReader you cannot access the document or {@link FieldCache}.
+ *
+ * @lucene.experimental
+ * @since 2.9.2
+ */
+public class CustomScoreProvider {
+
+ protected final IndexReader reader;
+
+ /**
+ * Creates a new instance of the provider class for the given {@link IndexReader}.
+ */
+ public CustomScoreProvider(IndexReader reader) {
+ this.reader = reader;
+ }
+
+ /**
+ * Compute a custom score by the subQuery score and a number of
+ * {@link ValueSourceQuery} scores.
+ *
+ * Subclasses can override this method to modify the custom score. + *
+ * If your custom scoring is different than the default herein you + * should override at least one of the two customScore() methods. + * If the number of ValueSourceQueries is always < 2 it is + * sufficient to override the other + * {@link #customScore(int, float, float) customScore()} + * method, which is simpler. + *
+ * The default computation herein is a multiplication of given scores: + *
+ * ModifiedScore = valSrcScore * valSrcScores[0] * valSrcScores[1] * ... + *+ * + * @param doc id of scored doc. + * @param subQueryScore score of that doc by the subQuery. + * @param valSrcScores scores of that doc by the ValueSourceQuery. + * @return custom score. + */ + public float customScore(int doc, float subQueryScore, float valSrcScores[]) throws IOException { + if (valSrcScores.length == 1) { + return customScore(doc, subQueryScore, valSrcScores[0]); + } + if (valSrcScores.length == 0) { + return customScore(doc, subQueryScore, 1); + } + float score = subQueryScore; + for(int i = 0; i < valSrcScores.length; i++) { + score *= valSrcScores[i]; + } + return score; + } + + /** + * Compute a custom score by the subQuery score and the ValueSourceQuery score. + *
+ * Subclasses can override this method to modify the custom score. + *
+ * If your custom scoring is different than the default herein you + * should override at least one of the two customScore() methods. + * If the number of ValueSourceQueries is always < 2 it is + * sufficient to override this customScore() method, which is simpler. + *
+ * The default computation herein is a multiplication of the two scores: + *
+ * ModifiedScore = subQueryScore * valSrcScore + *+ * + * @param doc id of scored doc. + * @param subQueryScore score of that doc by the subQuery. + * @param valSrcScore score of that doc by the ValueSourceQuery. + * @return custom score. + */ + public float customScore(int doc, float subQueryScore, float valSrcScore) throws IOException { + return subQueryScore * valSrcScore; + } + + /** + * Explain the custom score. + * Whenever overriding {@link #customScore(int, float, float[])}, + * this method should also be overridden to provide the correct explanation + * for the part of the custom scoring. + * + * @param doc doc being explained. + * @param subQueryExpl explanation for the sub-query part. + * @param valSrcExpls explanation for the value source part. + * @return an explanation for the custom score + */ + public Explanation customExplain(int doc, Explanation subQueryExpl, Explanation valSrcExpls[]) throws IOException { + if (valSrcExpls.length == 1) { + return customExplain(doc, subQueryExpl, valSrcExpls[0]); + } + if (valSrcExpls.length == 0) { + return subQueryExpl; + } + float valSrcScore = 1; + for (int i = 0; i < valSrcExpls.length; i++) { + valSrcScore *= valSrcExpls[i].getValue(); + } + Explanation exp = new Explanation( valSrcScore * subQueryExpl.getValue(), "custom score: product of:"); + exp.addDetail(subQueryExpl); + for (int i = 0; i < valSrcExpls.length; i++) { + exp.addDetail(valSrcExpls[i]); + } + return exp; + } + + /** + * Explain the custom score. + * Whenever overriding {@link #customScore(int, float, float)}, + * this method should also be overridden to provide the correct explanation + * for the part of the custom scoring. + * + * @param doc doc being explained. + * @param subQueryExpl explanation for the sub-query part. + * @param valSrcExpl explanation for the value source part. + * @return an explanation for the custom score + */ + public Explanation customExplain(int doc, Explanation subQueryExpl, Explanation valSrcExpl) throws IOException { + float valSrcScore = 1; + if (valSrcExpl != null) { + valSrcScore *= valSrcExpl.getValue(); + } + Explanation exp = new Explanation( valSrcScore * subQueryExpl.getValue(), "custom score: product of:"); + exp.addDetail(subQueryExpl); + exp.addDetail(valSrcExpl); + return exp; + } + +}