diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java index 95e5364756424..a12bd48f22242 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java @@ -932,6 +932,49 @@ public void onFailure(Exception e) { } } + 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 listener = new ActionListener() { + @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(); { diff --git a/docs/java-rest/high-level/document/exists.asciidoc b/docs/java-rest/high-level/document/exists.asciidoc new file mode 100644 index 0000000000000..d14c9fdd66a05 --- /dev/null +++ b/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 <>. +All of its <> +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. diff --git a/docs/java-rest/high-level/document/get.asciidoc b/docs/java-rest/high-level/document/get.asciidoc index 07a0b7c1a6721..9d04e138eea1e 100644 --- a/docs/java-rest/high-level/document/get.asciidoc +++ b/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: diff --git a/docs/java-rest/high-level/supported-apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc index fa2f57069ba93..79f17db577421 100644 --- a/docs/java-rest/high-level/supported-apis.asciidoc +++ b/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[]