From fcf125c226794a03ed9f710bc8b289724d027391 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Mon, 1 Oct 2018 17:09:12 -0400 Subject: [PATCH] Docs: DRY up CRUD docs This further applies the pattern set in #34125 to reduce copy-and-paste in the single document CRUD portion of the High Level REST Client docs. It also adds line wraps to snippets that are too wide to fit into the box when rendered in the docs, following up on the work started in #34163. --- .../documentation/CRUDDocumentationIT.java | 52 +++++---- .../high-level/document/delete.asciidoc | 71 ++++-------- .../high-level/document/exists.asciidoc | 51 ++------- .../high-level/document/get.asciidoc | 85 +++++--------- .../high-level/document/update.asciidoc | 105 +++++++----------- docs/java-rest/high-level/execution.asciidoc | 2 +- .../high-level/supported-apis.asciidoc | 1 + 7 files changed, 133 insertions(+), 234 deletions(-) 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 7d61ec0f3d97c..49b2ecb7a464b 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 @@ -176,7 +176,8 @@ public void testIndex() throws Exception { // <3> } if (shardInfo.getFailed() > 0) { - for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) { + for (ReplicationResponse.ShardInfo.Failure failure : + shardInfo.getFailures()) { String reason = failure.reason(); // <4> } } @@ -239,8 +240,9 @@ public void testIndex() throws Exception { } { IndexRequest request = new IndexRequest("posts", "doc", "async").source("field", "value"); + ActionListener listener; // tag::index-execute-listener - ActionListener listener = new ActionListener() { + listener = new ActionListener() { @Override public void onResponse(IndexResponse indexResponse) { // <1> @@ -305,8 +307,8 @@ public void testUpdate() throws Exception { request = new UpdateRequest("posts", "doc", "1").fetchSource(true); //tag::update-request-with-stored-script - Script stored = - new Script(ScriptType.STORED, null, "increment-field", parameters); // <1> + Script stored = new Script( + ScriptType.STORED, null, "increment-field", parameters); // <1> request.script(stored); // <2> //end::update-request-with-stored-script updateResponse = client.update(request, RequestOptions.DEFAULT); @@ -359,7 +361,8 @@ public void testUpdate() throws Exception { //end::update-request-with-doc-as-string request.fetchSource(true); // tag::update-execute - UpdateResponse updateResponse = client.update(request, RequestOptions.DEFAULT); + UpdateResponse updateResponse = client.update( + request, RequestOptions.DEFAULT); // end::update-execute assertEquals(DocWriteResponse.Result.UPDATED, updateResponse.getResult()); @@ -397,7 +400,8 @@ public void testUpdate() throws Exception { // <1> } if (shardInfo.getFailed() > 0) { - for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) { + for (ReplicationResponse.ShardInfo.Failure failure : + shardInfo.getFailures()) { String reason = failure.reason(); // <2> } } @@ -408,7 +412,8 @@ public void testUpdate() throws Exception { UpdateRequest request = new UpdateRequest("posts", "type", "does_not_exist") .doc("field", "value"); try { - UpdateResponse updateResponse = client.update(request, RequestOptions.DEFAULT); + UpdateResponse updateResponse = client.update( + request, RequestOptions.DEFAULT); } catch (ElasticsearchException e) { if (e.status() == RestStatus.NOT_FOUND) { // <1> @@ -422,7 +427,8 @@ public void testUpdate() throws Exception { .doc("field", "value") .version(1); try { - UpdateResponse updateResponse = client.update(request, RequestOptions.DEFAULT); + UpdateResponse updateResponse = client.update( + request, RequestOptions.DEFAULT); } catch(ElasticsearchException e) { if (e.status() == RestStatus.CONFLICT) { // <1> @@ -445,7 +451,8 @@ public void testUpdate() throws Exception { //tag::update-request-source-include String[] includes = new String[]{"updated", "r*"}; String[] excludes = Strings.EMPTY_ARRAY; - request.fetchSource(new FetchSourceContext(true, includes, excludes)); // <1> + request.fetchSource( + new FetchSourceContext(true, includes, excludes)); // <1> //end::update-request-source-include UpdateResponse updateResponse = client.update(request, RequestOptions.DEFAULT); assertEquals(DocWriteResponse.Result.UPDATED, updateResponse.getResult()); @@ -459,7 +466,8 @@ public void testUpdate() throws Exception { //tag::update-request-source-exclude String[] includes = Strings.EMPTY_ARRAY; String[] excludes = new String[]{"updated"}; - request.fetchSource(new FetchSourceContext(true, includes, excludes)); // <1> + request.fetchSource( + new FetchSourceContext(true, includes, excludes)); // <1> //end::update-request-source-exclude UpdateResponse updateResponse = client.update(request, RequestOptions.DEFAULT); assertEquals(DocWriteResponse.Result.UPDATED, updateResponse.getResult()); @@ -508,8 +516,9 @@ public void testUpdate() throws Exception { { UpdateRequest request = new UpdateRequest("posts", "doc", "async").doc("reason", "async update").docAsUpsert(true); + ActionListener listener; // tag::update-execute-listener - ActionListener listener = new ActionListener() { + listener = new ActionListener() { @Override public void onResponse(UpdateResponse updateResponse) { // <1> @@ -548,12 +557,13 @@ public void testDelete() throws Exception { // tag::delete-request DeleteRequest request = new DeleteRequest( "posts", // <1> - "doc", // <2> - "1"); // <3> + "doc", // <2> + "1"); // <3> // end::delete-request // tag::delete-execute - DeleteResponse deleteResponse = client.delete(request, RequestOptions.DEFAULT); + DeleteResponse deleteResponse = client.delete( + request, RequestOptions.DEFAULT); // end::delete-execute assertSame(DocWriteResponse.Result.DELETED, deleteResponse.getResult()); @@ -567,7 +577,8 @@ public void testDelete() throws Exception { // <1> } if (shardInfo.getFailed() > 0) { - for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) { + for (ReplicationResponse.ShardInfo.Failure failure : + shardInfo.getFailures()) { String reason = failure.reason(); // <2> } } @@ -598,7 +609,8 @@ public void testDelete() throws Exception { { // tag::delete-notfound DeleteRequest request = new DeleteRequest("posts", "doc", "does_not_exist"); - DeleteResponse deleteResponse = client.delete(request, RequestOptions.DEFAULT); + DeleteResponse deleteResponse = client.delete( + request, RequestOptions.DEFAULT); if (deleteResponse.getResult() == DocWriteResponse.Result.NOT_FOUND) { // <1> } @@ -612,8 +624,9 @@ public void testDelete() throws Exception { // tag::delete-conflict try { - DeleteRequest request = new DeleteRequest("posts", "doc", "1").version(2); - DeleteResponse deleteResponse = client.delete(request, RequestOptions.DEFAULT); + DeleteResponse deleteResponse = client.delete( + new DeleteRequest("posts", "doc", "1").version(2), + RequestOptions.DEFAULT); } catch (ElasticsearchException exception) { if (exception.status() == RestStatus.CONFLICT) { // <1> @@ -628,8 +641,9 @@ public void testDelete() throws Exception { DeleteRequest request = new DeleteRequest("posts", "doc", "async"); + ActionListener listener; // tag::delete-execute-listener - ActionListener listener = new ActionListener() { + listener = new ActionListener() { @Override public void onResponse(DeleteResponse deleteResponse) { // <1> diff --git a/docs/java-rest/high-level/document/delete.asciidoc b/docs/java-rest/high-level/document/delete.asciidoc index 5d263c894c663..1b32fca7042a7 100644 --- a/docs/java-rest/high-level/document/delete.asciidoc +++ b/docs/java-rest/high-level/document/delete.asciidoc @@ -1,14 +1,20 @@ -[[java-rest-high-document-delete]] +-- +:api: delete +:request: DeleteRequest +:response: DeleteResponse +-- + +[id="{upid}-{api}"] === Delete API -[[java-rest-high-document-delete-request]] +[id="{upid}-{api}-request"] ==== Delete Request -A `DeleteRequest` requires the following arguments: +A +{request}+ requires the following arguments: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request] +include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- <1> Index <2> Type @@ -19,82 +25,47 @@ The following arguments can optionally be provided: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-routing] +include-tagged::{doc-tests-file}[{api}-request-routing] -------------------------------------------------- <1> Routing value ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-timeout] +include-tagged::{doc-tests-file}[{api}-request-timeout] -------------------------------------------------- <1> Timeout to wait for primary shard to become available as a `TimeValue` <2> Timeout to wait for primary shard to become available as a `String` ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-refresh] +include-tagged::{doc-tests-file}[{api}-request-refresh] -------------------------------------------------- <1> Refresh policy as a `WriteRequest.RefreshPolicy` instance <2> Refresh policy as a `String` ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-version] +include-tagged::{doc-tests-file}[{api}-request-version] -------------------------------------------------- <1> Version ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-version-type] +include-tagged::{doc-tests-file}[{api}-request-version-type] -------------------------------------------------- <1> Version type -[[java-rest-high-document-delete-sync]] -==== Synchronous Execution - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute] --------------------------------------------------- - -[[java-rest-high-document-delete-async]] -==== Asynchronous Execution - -The asynchronous execution of a delete request requires both the `DeleteRequest` -instance and an `ActionListener` instance to be passed to the asynchronous -method: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute-async] --------------------------------------------------- -<1> The `DeleteRequest` 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 `DeleteResponse` looks like: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-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 +include::../execution.asciidoc[] -[[java-rest-high-document-delete-response]] +[id="{upid}-{api}-response"] ==== Delete Response -The returned `DeleteResponse` allows to retrieve information about the executed +The returned +{response}+ allows to retrieve information about the executed operation as follows: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-response] +include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- <1> Handle the situation where number of successful shards is less than total shards @@ -105,7 +76,7 @@ It is also possible to check whether the document was found or not: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-notfound] +include-tagged::{doc-tests-file}[{api}-notfound] -------------------------------------------------- <1> Do something if the document to be deleted was not found @@ -114,7 +85,7 @@ be thrown: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-conflict] +include-tagged::{doc-tests-file}[{api}-conflict] -------------------------------------------------- <1> The raised exception indicates that a version conflict error was returned diff --git a/docs/java-rest/high-level/document/exists.asciidoc b/docs/java-rest/high-level/document/exists.asciidoc index d14c9fdd66a05..ac6968d1f3752 100644 --- a/docs/java-rest/high-level/document/exists.asciidoc +++ b/docs/java-rest/high-level/document/exists.asciidoc @@ -1,12 +1,18 @@ -[[java-rest-high-document-exists]] +-- +:api: exists +:request: GetRequest +:response: boolean +-- + +[id="{upid}-{api}"] === Exists API The exists API returns `true` if a document exists, and `false` otherwise. -[[java-rest-high-document-exists-request]] +[id="{upid}-{api}-request"] ==== Exists Request -It uses `GetRequest` just like the <>. +It uses +{request}+ 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 @@ -14,7 +20,7 @@ slightly lighter: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-request] +include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- <1> Index <2> Type @@ -22,39 +28,4 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-request] <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. +include::../execution.asciidoc[] diff --git a/docs/java-rest/high-level/document/get.asciidoc b/docs/java-rest/high-level/document/get.asciidoc index 504b22a8e6dd7..f3ea9434f71c2 100644 --- a/docs/java-rest/high-level/document/get.asciidoc +++ b/docs/java-rest/high-level/document/get.asciidoc @@ -1,44 +1,50 @@ -[[java-rest-high-document-get]] +-- +:api: get +:request: GetRequest +:response: GetResponse +-- + +[id="{upid}-{api}"] === Get API -[[java-rest-high-document-get-request]] +[id="{upid}-{api}-request"] ==== Get Request -A `GetRequest` requires the following arguments: +A +{request}+ requires the following arguments: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request] +include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- <1> Index <2> Type <3> Document id -[[java-rest-high-document-get-request-optional-arguments]] +[id="{upid}-{api}-request-optional-arguments"] ==== Optional arguments The following arguments can optionally be provided: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-no-source] +include-tagged::{doc-tests-file}[{api}-request-no-source] -------------------------------------------------- <1> Disable source retrieval, enabled by default ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-source-include] +include-tagged::{doc-tests-file}[{api}-request-source-include] -------------------------------------------------- <1> Configure source inclusion for specific fields ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-source-exclude] +include-tagged::{doc-tests-file}[{api}-request-source-exclude] -------------------------------------------------- <1> Configure source exclusion for specific fields ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-stored] +include-tagged::{doc-tests-file}[{api}-request-stored] -------------------------------------------------- <1> Configure retrieval for specific stored fields (requires fields to be stored separately in the mappings) @@ -47,92 +53,57 @@ separately in the mappings) ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-routing] +include-tagged::{doc-tests-file}[{api}-request-routing] -------------------------------------------------- <1> Routing value ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-preference] +include-tagged::{doc-tests-file}[{api}-request-preference] -------------------------------------------------- <1> Preference value ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-realtime] +include-tagged::{doc-tests-file}[{api}-request-realtime] -------------------------------------------------- <1> Set realtime flag to `false` (`true` by default) ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-refresh] +include-tagged::{doc-tests-file}[{api}-request-refresh] -------------------------------------------------- <1> Perform a refresh before retrieving the document (`false` by default) ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-version] +include-tagged::{doc-tests-file}[{api}-request-version] -------------------------------------------------- <1> Version ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-request-version-type] +include-tagged::{doc-tests-file}[{api}-request-version-type] -------------------------------------------------- <1> Version type -[[java-rest-high-document-get-sync]] -==== Synchronous Execution - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-execute] --------------------------------------------------- - -[[java-rest-high-document-get-async]] -==== Asynchronous Execution - -The asynchronous execution of a get 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[get-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[get-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. +include::../execution.asciidoc[] -[[java-rest-high-document-get-response]] +[id="{upid}-{api}-response"] ==== Get Response -The returned `GetResponse` allows to retrieve the requested document along with +The returned +{response}+ allows to retrieve the requested document along with its metadata and eventually stored fields. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-response] +include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- <1> Retrieve the document as a `String` <2> Retrieve the document as a `Map` <3> Retrieve the document as a `byte[]` <4> Handle the scenario where the document was not found. Note that although -the returned response has `404` status code, a valid `GetResponse` is +the returned response has `404` status code, a valid +{response}+ is returned rather than an exception thrown. Such response does not hold any source document and its `isExists` method returns `false`. @@ -142,7 +113,7 @@ which needs to be handled as follows: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-indexnotfound] +include-tagged::{doc-tests-file}[{api}-indexnotfound] -------------------------------------------------- <1> Handle the exception thrown because the index does not exist @@ -151,6 +122,6 @@ document has a different version number, a version conflict is raised: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[get-conflict] +include-tagged::{doc-tests-file}[{api}-conflict] -------------------------------------------------- <1> The raised exception indicates that a version conflict error was returned diff --git a/docs/java-rest/high-level/document/update.asciidoc b/docs/java-rest/high-level/document/update.asciidoc index 1c780093115d8..743eb3da0a806 100644 --- a/docs/java-rest/high-level/document/update.asciidoc +++ b/docs/java-rest/high-level/document/update.asciidoc @@ -1,14 +1,20 @@ -[[java-rest-high-document-update]] +-- +:api: update +:request: UpdateRequest +:response: UpdateResponse +-- + +[id="{upid}-{api}"] === Update API -[[java-rest-high-document-update-request]] +[id="{upid}-{api}-request"] ==== Update Request -An `UpdateRequest` requires the following arguments: +An +{request}+ requires the following arguments: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request] +include-tagged::{doc-tests-file}[{api}-request] -------------------------------------------------- <1> Index <2> Type @@ -22,7 +28,7 @@ The script can be provided as an inline script: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-with-inline-script] +include-tagged::{doc-tests-file}[{api}-request-with-inline-script] -------------------------------------------------- <1> Script parameters provided as a `Map` of objects <2> Create an inline script using the `painless` language and the previous parameters @@ -32,7 +38,7 @@ Or as a stored script: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-with-stored-script] +include-tagged::{doc-tests-file}[{api}-request-with-stored-script] -------------------------------------------------- <1> Reference to a script stored under the name `increment-field` in the `painless` language <2> Sets the script in the update request @@ -45,27 +51,27 @@ The partial document can be provided in different ways: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-with-doc-as-string] +include-tagged::{doc-tests-file}[{api}-request-with-doc-as-string] -------------------------------------------------- <1> Partial document source provided as a `String` in JSON format ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-with-doc-as-map] +include-tagged::{doc-tests-file}[{api}-request-with-doc-as-map] -------------------------------------------------- <1> Partial document source provided as a `Map` which gets automatically converted to JSON format ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-with-doc-as-xcontent] +include-tagged::{doc-tests-file}[{api}-request-with-doc-as-xcontent] -------------------------------------------------- <1> Partial document source provided as an `XContentBuilder` object, the Elasticsearch built-in helpers to generate JSON content ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-shortcut] +include-tagged::{doc-tests-file}[{api}-request-shortcut] -------------------------------------------------- <1> Partial document source provided as `Object` key-pairs, which gets converted to JSON format @@ -76,7 +82,7 @@ will be inserted as a new document using the `upsert` method: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-upsert] +include-tagged::{doc-tests-file}[{api}-request-upsert] -------------------------------------------------- <1> Upsert document source provided as a `String` @@ -89,27 +95,27 @@ The following arguments can optionally be provided: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-routing] +include-tagged::{doc-tests-file}[{api}-request-routing] -------------------------------------------------- <1> Routing value ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-timeout] +include-tagged::{doc-tests-file}[{api}-request-timeout] -------------------------------------------------- <1> Timeout to wait for primary shard to become available as a `TimeValue` <2> Timeout to wait for primary shard to become available as a `String` ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-refresh] +include-tagged::{doc-tests-file}[{api}-request-refresh] -------------------------------------------------- <1> Refresh policy as a `WriteRequest.RefreshPolicy` instance <2> Refresh policy as a `String` ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-retry] +include-tagged::{doc-tests-file}[{api}-request-retry] -------------------------------------------------- <1> How many times to retry the update operation if the document to update has been changed by another operation between the get and indexing phases of the @@ -117,103 +123,68 @@ update operation ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-no-source] +include-tagged::{doc-tests-file}[{api}-request-no-source] -------------------------------------------------- <1> Enable source retrieval, disabled by default ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-source-include] +include-tagged::{doc-tests-file}[{api}-request-source-include] -------------------------------------------------- <1> Configure source inclusion for specific fields ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-source-exclude] +include-tagged::{doc-tests-file}[{api}-request-source-exclude] -------------------------------------------------- <1> Configure source exclusion for specific fields ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-version] +include-tagged::{doc-tests-file}[{api}-request-version] -------------------------------------------------- <1> Version ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-detect-noop] +include-tagged::{doc-tests-file}[{api}-request-detect-noop] -------------------------------------------------- <1> Disable the noop detection ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-scripted-upsert] +include-tagged::{doc-tests-file}[{api}-request-scripted-upsert] -------------------------------------------------- <1> Indicate that the script must run regardless of whether the document exists or not, ie the script takes care of creating the document if it does not already exist. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-doc-upsert] +include-tagged::{doc-tests-file}[{api}-request-doc-upsert] -------------------------------------------------- <1> Indicate that the partial document must be used as the upsert document if it does not exist yet. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-request-active-shards] +include-tagged::{doc-tests-file}[{api}-request-active-shards] -------------------------------------------------- <1> Sets the number of shard copies that must be active before proceeding with the update operation. <2> Number of shard copies provided as a `ActiveShardCount`: can be `ActiveShardCount.ALL`, `ActiveShardCount.ONE` or `ActiveShardCount.DEFAULT` (default) -[[java-rest-high-document-update-sync]] -==== Synchronous Execution - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-execute] --------------------------------------------------- - -[[java-rest-high-document-update-async]] -==== Asynchronous Execution - -The asynchronous execution of an update request requires both the `UpdateRequest` -instance and an `ActionListener` instance to be passed to the asynchronous -method: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-execute-async] --------------------------------------------------- -<1> The `UpdateRequest` 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 `UpdateResponse` looks like: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-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. +include::../execution.asciidoc[] -[[java-rest-high-document-update-response]] +[id="{upid}-{api}-response"] ==== Update Response -The returned `UpdateResponse` allows to retrieve information about the executed - operation as follows: +The returned +{response}+ allows to retrieve information about the executed +operation as follows: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-response] +include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- <1> Handle the case where the document was created for the first time (upsert) <2> Handle the case where the document was updated @@ -227,7 +198,7 @@ source of the updated document: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-getresult] +include-tagged::{doc-tests-file}[{api}-getresult] -------------------------------------------------- <1> Retrieve the updated document as a `GetResult` <2> Retrieve the source of the updated document as a `String` @@ -240,7 +211,7 @@ It is also possible to check for shard failures: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-failure] +include-tagged::{doc-tests-file}[{api}-failure] -------------------------------------------------- <1> Handle the situation where number of successful shards is less than total shards @@ -252,7 +223,7 @@ which needs to be handled as follows: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-docnotfound] +include-tagged::{doc-tests-file}[{api}-docnotfound] -------------------------------------------------- <1> Handle the exception thrown because the document not exist @@ -261,6 +232,6 @@ be thrown: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[update-conflict] +include-tagged::{doc-tests-file}[{api}-conflict] -------------------------------------------------- <1> The raised exception indicates that a version conflict error was returned. diff --git a/docs/java-rest/high-level/execution.asciidoc b/docs/java-rest/high-level/execution.asciidoc index fc4f4c0ec609e..4dfb11e196d9e 100644 --- a/docs/java-rest/high-level/execution.asciidoc +++ b/docs/java-rest/high-level/execution.asciidoc @@ -38,7 +38,7 @@ 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 +{response}+ looks like: +A typical listener for +{api}+ looks like: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- diff --git a/docs/java-rest/high-level/supported-apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc index 306506411ee74..6485cf5696be0 100644 --- a/docs/java-rest/high-level/supported-apis.asciidoc +++ b/docs/java-rest/high-level/supported-apis.asciidoc @@ -11,6 +11,7 @@ The Java High Level REST Client supports the following Document APIs: Single document APIs:: * <<{upid}-index>> * <<{upid}-get>> +* <<{upid}-exists>> * <<{upid}-delete>> * <<{upid}-update>>