Scripting: Rename SearchScript.needsScores to needs_score (#25235)

This commit renames the needsScores method so as to make it
automatically generatable, based on the name of the `_score` variable
which is available in search scripts. It also adds documentation to
ScriptContext to explain the naming and signature of such methods.

core/src/main/java/org/elasticsearch/common/lucene/search/function/ScriptScoreFunction.java

@@ -119,7 +119,7 @@ public class ScriptScoreFunction extends ScoreFunction {
 
     @Override
     public boolean needsScores() {
-        return script.needsScores();
+        return script.needs_score();
     }
 
     @Override

core/src/main/java/org/elasticsearch/script/ScriptContext.java

@@ -46,6 +46,13 @@ import java.lang.reflect.Method;
  * The <i>StatefulFactoryType</i> is an optional class which allows a stateful factory from the
  * stateless factory type required by the {@link ScriptService}. If defined, the <i>StatefulFactoryType</i>
  * must have a method named {@code newInstance} which returns an instance of <i>InstanceType</i>.
+ * <p>
+ * Both the <i>FactoryType</i> and <i>StatefulFactoryType</i> may have abstract methods to indicate
+ * whether a variable is used in a script. These method should return a {@code boolean} and their name
+ * should start with {@code needs}, followed by the variable name, with the first letter uppercased.
+ * For example, to check if a variable {@code doc} is used, a method {@code boolean needsDoc()} should be added.
+ * If the variable name starts with an underscore, for example, {@code _score}, the needs method would
+ * be {@code boolean needs_score()}.
  */
 public final class ScriptContext<FactoryType> {
 

core/src/main/java/org/elasticsearch/script/SearchScript.java

@@ -144,12 +144,11 @@ public abstract class SearchScript implements ScorerAware, ExecutableScript {
     /** A factory to construct {@link SearchScript} instances. */
     public interface LeafFactory {
         SearchScript newInstance(LeafReaderContext ctx) throws IOException;
+
         /**
-         * Indicates if document scores may be needed by this {@link SearchScript}.
-         *
-         * @return {@code true} if scores are needed.
+         * Return {@code true} if the script needs {@code _score} calculated, or {@code false} otherwise.
          */
-        boolean needsScores();
+        boolean needs_score();
     }
 
     /** A factory to construct stateful {@link SearchScript} factories for a specific index. */

core/src/main/java/org/elasticsearch/search/aggregations/support/ValuesSource.java

@@ -174,7 +174,7 @@ public abstract class ValuesSource {
 
             @Override
             public boolean needsScores() {
-                return script.needsScores();
+                return script.needs_score();
             }
         }
 
@@ -246,7 +246,7 @@ public abstract class ValuesSource {
 
             @Override
             public boolean needsScores() {
-                return script.needsScores();
+                return script.needs_score();
             }
 
             @Override
@@ -387,7 +387,7 @@ public abstract class ValuesSource {
 
             @Override
             public boolean needsScores() {
-                return script.needsScores();
+                return script.needs_score();
             }
         }
 
@@ -406,7 +406,7 @@ public abstract class ValuesSource {
 
         @Override
         public boolean needsScores() {
-            return script.needsScores();
+            return script.needs_score();
         }
 
         @Override

core/src/test/java/org/elasticsearch/common/lucene/search/function/ScriptScoreFunctionTests.java

@@ -44,7 +44,7 @@ public class ScriptScoreFunctionTests extends ESTestCase {
             }
             
             @Override
-            public boolean needsScores() {
+            public boolean needs_score() {
                 return false;
             }
         });

core/src/test/java/org/elasticsearch/search/functionscore/ExplainableScriptIT.java

@@ -83,7 +83,7 @@ public class ExplainableScriptIT extends ESIntegTestCase {
                             return new MyScript(lookup.doc().getLeafDocLookup(context));
                         }
                         @Override
-                        public boolean needsScores() {
+                        public boolean needs_score() {
                             return false;
                         }
                     };

modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionSearchScript.java

@@ -54,7 +54,7 @@ class ExpressionSearchScript implements SearchScript.LeafFactory {
     }
 
     @Override
-    public boolean needsScores() {
+    public boolean needs_score() {
         return needsScores;
     }
 

modules/lang-expression/src/test/java/org/elasticsearch/script/expression/ExpressionTests.java

@@ -47,10 +47,10 @@ public class ExpressionTests extends ESSingleNodeTestCase {
     }
 
     public void testNeedsScores() {
-        assertFalse(compile("1.2").needsScores());
-        assertFalse(compile("doc['d'].value").needsScores());
-        assertTrue(compile("1/_score").needsScores());
-        assertTrue(compile("doc['d'].value * _score").needsScores());
+        assertFalse(compile("1.2").needs_score());
+        assertFalse(compile("doc['d'].value").needs_score());
+        assertTrue(compile("1/_score").needs_score());
+        assertTrue(compile("doc['d'].value * _score").needs_score());
     }
 
     public void testCompileError() {

modules/lang-painless/src/main/java/org/elasticsearch/painless/PainlessScriptEngine.java

@@ -134,7 +134,7 @@ public final class PainlessScriptEngine extends AbstractComponent implements Scr
                     return new ScriptImpl(painlessScript, p, lookup, context);
                 }
                 @Override
-                public boolean needsScores() {
+                public boolean needs_score() {
                     return painlessScript.needs_score();
                 }
             };

modules/lang-painless/src/test/java/org/elasticsearch/painless/NeedsScoreTests.java

@@ -44,19 +44,19 @@ public class NeedsScoreTests extends ESSingleNodeTestCase {
 
         SearchScript.Factory factory = service.compile(null, "1.2", SearchScript.CONTEXT, Collections.emptyMap());
         SearchScript.LeafFactory ss = factory.newFactory(Collections.emptyMap(), lookup);
-        assertFalse(ss.needsScores());
+        assertFalse(ss.needs_score());
 
         factory = service.compile(null, "doc['d'].value", SearchScript.CONTEXT, Collections.emptyMap());
         ss = factory.newFactory(Collections.emptyMap(), lookup);
-        assertFalse(ss.needsScores());
+        assertFalse(ss.needs_score());
 
         factory = service.compile(null, "1/_score", SearchScript.CONTEXT, Collections.emptyMap());
         ss = factory.newFactory(Collections.emptyMap(), lookup);
-        assertTrue(ss.needsScores());
+        assertTrue(ss.needs_score());
 
         factory = service.compile(null, "doc['d'].value * _score", SearchScript.CONTEXT, Collections.emptyMap());
         ss = factory.newFactory(Collections.emptyMap(), lookup);
-        assertTrue(ss.needsScores());
+        assertTrue(ss.needs_score());
     }
 
 }

plugins/examples/script-expert-scoring/src/main/java/org/elasticsearch/example/expertscript/ExpertScriptPlugin.java

@@ -115,7 +115,7 @@ public class ExpertScriptPlugin extends Plugin implements ScriptPlugin {
                     }
 
                     @Override
-                    public boolean needsScores() {
+                    public boolean needs_score() {
                         return false;
                     }
                 };

test/framework/src/main/java/org/elasticsearch/script/MockScriptEngine.java

@@ -219,7 +219,7 @@ public class MockScriptEngine implements ScriptEngine {
         }
 
         @Override
-        public boolean needsScores() {
+        public boolean needs_score() {
             return true;
         }
     }