Merge pull request #13996 from nik9000/native_scripts

Rewrite native script documentation

docs/reference/modules/scripting.asciidoc

@@ -351,28 +351,86 @@ to `false`.
 [float]
 === Native (Java) Scripts
 
-Even though `groovy` is pretty fast, this allows to register native Java based
+Sometimes `groovy` and `expressions` aren't enough. For those times you can
-scripts for faster execution.
+implement a native script.
 
-In order to allow for scripts, the `NativeScriptFactory` needs to be
+The best way to implement a native script is to write a plugin and install it.
-implemented that constructs the script that will be executed. There are
+The plugin {plugins}/plugin-authors.html[documentation] has more information on
-two main types, one that extends `AbstractExecutableScript` and one that
+how to write a plugin so that Elasticsearch will properly load it.
-extends `AbstractSearchScript` (probably the one most users will extend,
-with additional helper classes in `AbstractLongSearchScript`,
-`AbstractDoubleSearchScript`, and `AbstractFloatSearchScript`).
 
-Registering them can either be done by settings, for example:
+To register the actual script you'll need to implement `NativeScriptFactory`
-`script.native.my.type` set to `sample.MyNativeScriptFactory` will
+to construct the script. The actual script will extend either
-register a script named `my`. Another option is in a plugin, access
+`AbstractExecutableScript` or `AbstractSearchScript`. The second one is likely
-`ScriptModule` and call `registerScript` on it.
+the most useful and has several helpful subclasses you can extend like
+`AbstractLongSearchScript`, `AbstractDoubleSearchScript`, and
+`AbstractFloatSearchScript`. Finally, your plugin should register the native
+script by declaring the `onModule(ScriptModule)` method.
 
-Executing the script is done by specifying the `lang` as `native`, and
+If you squashed the whole thing into one class it'd look like:
-the name of the script as the `script`.
+
+[source,java]
+--------------------------------------------------
+public class MyNativeScriptPlugin extends Plugin {
+    @Override
+    public String name() {
+        return "my-native-script";
+    }
+    @Override
+    public String description() {
+        return "my native script that does something great";
+    }
+    public void onModule(ScriptModule scriptModule) {
+        scriptModule.registerScript("my_script", MyNativeScriptFactory.class);
+    }
+
+    public static class MyNativeScriptFactory implements NativeScriptFactory {
+        @Override
+        public ExecutableScript newScript(@Nullable Map<String, Object> params) {
+            return new MyNativeScript();
+        }
+        @Override
+        public boolean needsScores() {
+            return false;
+        }
+    }
+
+    public static class MyNativeScript extends AbstractFloatSearchScript {
+        @Override
+        public float runAsFloat() {
+            float a = (float) source().get("a");
+            float b = (float) source().get("b");
+            return a * b;
+        }
+    }
+}
+--------------------------------------------------
+
+You can execute the script by specifying its `lang` as `native`, and the name
+of the script as the `id`:
+
+[source,js]
+--------------------------------------------------
+curl -XPOST localhost:9200/_search -d '{
+  "query": {
+    "function_score": {
+      "query": {
+        "match": {
+          "body": "foo"
+        }
+      },
+      "functions": [
+        {
+          "script_score": {
+            "id": "my_script",
+            "lang" : "native"
+          }
+        }
+      ]
+    }
+  }
+}'
+--------------------------------------------------
 
-Note, the scripts need to be in the classpath of elasticsearch. One
-simple way to do it is to create a directory under plugins (choose a
-descriptive name), and place the jar / classes files there. They will be
-automatically loaded.
 
 [float]
 === Lucene Expressions Scripts