From a77c824476605a5363c85acdd07a5b578e9c1fe6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nicolas=20Laleve=CC=81e?= <nicolas.lalevee@hibnet.org>
Date: Thu, 5 Jul 2012 17:45:08 +0200
Subject: [PATCH] Add an interface to be implemented by native scripts to be
 able to explain the score

---
 .../index/query/CustomScoreQueryParser.java   | 12 +++++--
 .../script/ExplanableSearchScript.java        | 35 +++++++++++++++++++
 .../elasticsearch/script/SearchScript.java    |  2 ++
 3 files changed, 47 insertions(+), 2 deletions(-)
 create mode 100644 src/main/java/org/elasticsearch/script/ExplanableSearchScript.java

diff --git a/src/main/java/org/elasticsearch/index/query/CustomScoreQueryParser.java b/src/main/java/org/elasticsearch/index/query/CustomScoreQueryParser.java
index 91c1c182906..73f55ce7b6d 100644
--- a/src/main/java/org/elasticsearch/index/query/CustomScoreQueryParser.java
+++ b/src/main/java/org/elasticsearch/index/query/CustomScoreQueryParser.java
@@ -27,6 +27,7 @@ import org.elasticsearch.common.inject.Inject;
 import org.elasticsearch.common.lucene.search.function.FunctionScoreQuery;
 import org.elasticsearch.common.lucene.search.function.ScoreFunction;
 import org.elasticsearch.common.xcontent.XContentParser;
+import org.elasticsearch.script.ExplanableSearchScript;
 import org.elasticsearch.script.SearchScript;
 
 import java.io.IOException;
@@ -141,8 +142,15 @@ public class CustomScoreQueryParser implements QueryParser {
 
         @Override
         public Explanation explainScore(int docId, Explanation subQueryExpl) {
-            float score = score(docId, subQueryExpl.getValue());
-            Explanation exp = new Explanation(score, "script score function: product of:");
+            Explanation exp;
+            if (script instanceof ExplanableSearchScript) {
+                script.setNextDocId(docId);
+                script.setNextScore(subQueryExpl.getValue());
+                exp = ((ExplanableSearchScript)  script).explain();
+            } else {
+                float score = score(docId, subQueryExpl.getValue());
+                exp = new Explanation(score, "script score function: product of:");
+            }
             exp.addDetail(subQueryExpl);
             return exp;
         }
diff --git a/src/main/java/org/elasticsearch/script/ExplanableSearchScript.java b/src/main/java/org/elasticsearch/script/ExplanableSearchScript.java
new file mode 100644
index 00000000000..638aa961fa4
--- /dev/null
+++ b/src/main/java/org/elasticsearch/script/ExplanableSearchScript.java
@@ -0,0 +1,35 @@
+/*
+ * Licensed to Elastic Search under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. Elastic Search licenses this
+ * file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.script;
+
+import org.apache.lucene.search.Explanation;
+
+/**
+ * To be implemented by {@link SearchScript} which can provided an {@link Explanation} of the score
+ */
+public interface ExplanableSearchScript {
+
+    /**
+     * Build the explanation of the current document being scored
+     * 
+     * @return
+     */
+    Explanation explain();
+
+}
diff --git a/src/main/java/org/elasticsearch/script/SearchScript.java b/src/main/java/org/elasticsearch/script/SearchScript.java
index b06c4a92b19..d061d3a4eae 100644
--- a/src/main/java/org/elasticsearch/script/SearchScript.java
+++ b/src/main/java/org/elasticsearch/script/SearchScript.java
@@ -26,6 +26,8 @@ import java.util.Map;
 
 /**
  * A search script.
+ * 
+ * @see ExplanableSearchScript for script which can explain a score
  */
 public interface SearchScript extends ExecutableScript {