From 514e8bedfc18a754df4c27917ac731e4a3fe0da0 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Wed, 14 Mar 2018 15:40:29 -0400 Subject: [PATCH 1/3] Docs: HighLevelRestClient#exists Add documentation for `HighLevelRestClient#exists`. Relates to #28389 --- .../documentation/CRUDDocumentationIT.java | 43 ++++++++++++++ .../high-level/document/exists.asciidoc | 59 +++++++++++++++++++ .../high-level/document/get.asciidoc | 1 + .../high-level/supported-apis.asciidoc | 1 + 4 files changed, 104 insertions(+) create mode 100644 docs/java-rest/high-level/document/exists.asciidoc 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 16fa4f8d69cfb..7fd18e66b6df4 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..d767a1e656b89 --- /dev/null +++ b/docs/java-rest/high-level/document/exists.asciidoc @@ -0,0 +1,59 @@ +[[java-rest-high-document-exists]] +=== Exists API + +[[java-rest-high-document-exists-request]] +==== Exists Request + +The `exists()` API is `true` if a document exists, and `false` otherwise. +It uses `GetRequest` just like the <>. +All of its <> +are supported. + +["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`. Since `exists()` just returns `true` or +`false`, we don't need to ask Elasticsearch to load the `_source`. +<5> Disable fetching stored fields. Since `exists()` just returns `true` +or `false`, we don't need to ask Elasticsearch to load 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()` 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[] From e213c8dd666de2ae08c3e054edaef95e1a84e868 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Wed, 14 Mar 2018 15:43:50 -0400 Subject: [PATCH 2/3] Explain --- docs/java-rest/high-level/document/exists.asciidoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/java-rest/high-level/document/exists.asciidoc b/docs/java-rest/high-level/document/exists.asciidoc index d767a1e656b89..58a325ed3f95c 100644 --- a/docs/java-rest/high-level/document/exists.asciidoc +++ b/docs/java-rest/high-level/document/exists.asciidoc @@ -7,7 +7,9 @@ The `exists()` API is `true` if a document exists, and `false` otherwise. It uses `GetRequest` just like the <>. All of its <> -are supported. +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"] -------------------------------------------------- @@ -16,10 +18,8 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-request] <1> Index <2> Type <3> Document id -<4> Disable fetching `_source`. Since `exists()` just returns `true` or -`false`, we don't need to ask Elasticsearch to load the `_source`. -<5> Disable fetching stored fields. Since `exists()` just returns `true` -or `false`, we don't need to ask Elasticsearch to load stored fields. +<4> Disable fetching `_source`. +<5> Disable fetching stored fields. [[java-rest-high-document-exists-sync]] ==== Synchronous Execution From 955463d4fbd9008bdf1ba7a041f2801fe8e29821 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Thu, 15 Mar 2018 12:00:43 -0400 Subject: [PATCH 3/3] Cleanup --- docs/java-rest/high-level/document/exists.asciidoc | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/java-rest/high-level/document/exists.asciidoc b/docs/java-rest/high-level/document/exists.asciidoc index 58a325ed3f95c..d14c9fdd66a05 100644 --- a/docs/java-rest/high-level/document/exists.asciidoc +++ b/docs/java-rest/high-level/document/exists.asciidoc @@ -1,13 +1,14 @@ [[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 -The `exists()` API is `true` if a document exists, and `false` otherwise. It uses `GetRequest` just like the <>. All of its <> -are supported. Since `exists()` only returns `true` or false, we recommend +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: @@ -32,7 +33,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-execute] [[java-rest-high-document-exists-async]] ==== Asynchronous Execution -The asynchronous execution of `exists()` requires both the `GetRequest` +The asynchronous execution of exists request requires both the `GetRequest` instance and an `ActionListener` instance to be passed to the asynchronous method: @@ -41,7 +42,7 @@ method: include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-execute-async] -------------------------------------------------- <1> The `GetRequest` to execute and the `ActionListener` to use when -the execution completes +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