Docs: HighLevelRestClient#exists (#29073)

Docs: HighLevelRestClient#exists

Add documentation for `HighLevelRestClient#exists`.

Relates to #28389

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java

@@ -932,6 +932,49 @@ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase {
         }
     }
 
+    public void testExists() throws Exception {
+        RestHighLevelClient client = highLevelClient();
+        // tag::exists-request
+        GetRequest getRequest = new GetRequest(
+            "posts", // <1>
+            "doc",   // <2>
+            "1");    // <3>
+        getRequest.fetchSourceContext(new FetchSourceContext(false)); // <4>
+        getRequest.storedFields("_none_");                            // <5>
+        // end::exists-request
+        {
+            // tag::exists-execute
+            boolean exists = client.exists(getRequest);
+            // end::exists-execute
+            assertFalse(exists);
+        }
+        {
+            // tag::exists-execute-listener
+            ActionListener<Boolean> listener = new ActionListener<Boolean>() {
+                @Override
+                public void onResponse(Boolean exists) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            };
+            // end::exists-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener<>(listener, latch);
+
+            // tag::exists-execute-async
+            client.existsAsync(getRequest, listener); // <1>
+            // end::exists-execute-async
+
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
+        }
+    }
+
     public void testBulkProcessor() throws InterruptedException {
         RestHighLevelClient client = highLevelClient();
         {

docs/java-rest/high-level/document/exists.asciidoc

@@ -0,0 +1,60 @@
+[[java-rest-high-document-exists]]
+=== Exists API
+
+The exists API returns `true` if a document exists, and `false` otherwise.
+
+[[java-rest-high-document-exists-request]]
+==== Exists Request
+
+It uses `GetRequest` just like the <<java-rest-high-document-get>>.
+All of its <<java-rest-high-document-get-request-optional-arguments, optional arguments>>
+are supported. Since `exists()` only returns `true` or `false`, we recommend
+turning off fetching `_source` and any stored fields so the request is
+slightly lighter:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-request]
+--------------------------------------------------
+<1> Index
+<2> Type
+<3> Document id
+<4> Disable fetching `_source`.
+<5> Disable fetching stored fields.
+
+[[java-rest-high-document-exists-sync]]
+==== Synchronous Execution
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-execute]
+--------------------------------------------------
+
+[[java-rest-high-document-exists-async]]
+==== Asynchronous Execution
+
+The asynchronous execution of exists request requires both the `GetRequest`
+instance and an `ActionListener` instance to be passed to the asynchronous
+method:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-execute-async]
+--------------------------------------------------
+<1> The `GetRequest` to execute and the `ActionListener` to use when
+the execution completes.
+
+The asynchronous method does not block and returns immediately. Once it is
+completed 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 `GetResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-execute-listener]
+--------------------------------------------------
+<1> Called when the execution is successfully completed. The response is
+provided as an argument.
+<2> Called in case of failure. The raised exception is provided as an argument.

docs/java-rest/high-level/document/get.asciidoc

@@ -14,6 +14,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request]
 <2> Type
 <3> Document id
 
+[[java-rest-high-document-get-request-optional-arguments]]
 ==== Optional arguments
 The following arguments can optionally be provided:
 

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

@@ -17,6 +17,7 @@ Multi-document APIs::
 
 include::document/index.asciidoc[]
 include::document/get.asciidoc[]
+include::document/exists.asciidoc[]
 include::document/delete.asciidoc[]
 include::document/update.asciidoc[]
 include::document/bulk.asciidoc[]