Add explain API to high-level REST client (#31387)

Relates to #27205

docs/java-rest/high-level/search/explain.asciidoc

@@ -0,0 +1,113 @@
+[[java-rest-high-explain]]
+=== Explain API
+
+The explain api computes a score explanation for a query and a specific document.
+This can give useful feedback whether a document matches or didn’t match a specific query.
+
+[[java-rest-high-explain-request]]
+==== Explain Request
+
+An `ExplainRequest` expects an `index`, a `type` and an `id` to specify a certain document,
+and a query represented by `QueryBuilder` to run against it (the way of <<java-rest-high-query-builders, building queries>>).
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[explain-request]
+--------------------------------------------------
+
+===== Optional arguments
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[explain-request-routing]
+--------------------------------------------------
+<1> Set a routing parameter
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[explain-request-preference]
+--------------------------------------------------
+<1> Use the preference parameter e.g. to execute the search to prefer local
+shards. The default is to randomize across shards.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[explain-request-source]
+--------------------------------------------------
+<1> Set to true to retrieve the _source of the document explained. You can also
+retrieve part of the document by using _source_include & _source_exclude
+(see <<java-rest-high-document-get-request-optional-arguments, Get API>> for more details)
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[explain-request-stored-field]
+--------------------------------------------------
+<1> Allows to control which stored fields to return as part of the document explained
+(requires the field to be stored separately in the mappings).
+
+[[java-rest-high-explain-sync]]
+==== Synchronous Execution
+
+The `explain` method executes the request synchronously:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[explain-execute]
+--------------------------------------------------
+
+[[java-rest-high-explain-async]]
+==== Asynchronous Execution
+
+The `explainAsync` method executes the request asynchronously,
+calling the provided `ActionListener` when the response is ready:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[explain-execute-async]
+--------------------------------------------------
+<1> The `ExplainRequest` to execute and the `ActionListener` to use when
+the execution completes.
+
+The asynchronous method does not block and returns immediately. Once the request
+completes, the `ActionListener` is called back using the `onResponse` method
+if the execution successfully completed or using the `onFailure` method if
+it failed.
+
+A typical listener for `ExplainResponse` is constructed as follows:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[explain-execute-listener]
+--------------------------------------------------
+<1> Called when the execution is successfully completed.
+<2> Called when the whole `FieldCapabilitiesRequest` fails.
+
+[[java-rest-high-explain-response]]
+==== ExplainResponse
+
+The `ExplainResponse` contains the following information:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[explain-response]
+--------------------------------------------------
+<1> The index name of the explained document.
+<2> The type name of the explained document.
+<3> The id of the explained document.
+<4> Indicates whether or not the explained document exists.
+<5> Indicates whether or not there is a match between the explained document and
+the provided query (the `match` is retrieved from the lucene `Explanation` behind the scenes
+if the lucene `Explanation` models a match, it returns `true`, otherwise it returns `false`).
+<6> Indicates whether or not there exists a lucene `Explanation` for this request.
+<7> Get the lucene `Explanation` object if there exists.
+<8> Get the `GetResult` object if the `_source` or the stored fields are retrieved.
+
+The `GetResult` contains two maps internally to store the fetched `_source` and stored fields.
+You can use the following methods to get them:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/SearchDocumentationIT.java[get-result]
+--------------------------------------------------
+<1> Retrieve the `_source` as a map.
+<2> Retrieve the specified stored fields as a map.

docs/java-rest/high-level/supported-apis.asciidoc

@@ -35,6 +35,7 @@ The Java High Level REST Client supports the following Search APIs:
 * <<java-rest-high-multi-search>>
 * <<java-rest-high-field-caps>>
 * <<java-rest-high-rank-eval>>
+* <<java-rest-high-explain>>
 
 include::search/search.asciidoc[]
 include::search/scroll.asciidoc[]
@@ -42,6 +43,7 @@ include::search/multi-search.asciidoc[]
 include::search/search-template.asciidoc[]
 include::search/field-caps.asciidoc[]
 include::search/rank-eval.asciidoc[]
+include::search/explain.asciidoc[]
 
 == Miscellaneous APIs