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 6584381223c..79d2ccacf61 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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { // <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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { } { 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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { 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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { //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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { // <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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { 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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { .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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { //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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { //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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { { 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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { // 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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { // <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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { { // 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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { // 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 class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { 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 5d263c894c6..1b32fca7042 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 +include::../execution.asciidoc[] -["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 - -[[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 d14c9fdd66a..ac6968d1f37 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 504b22a8e6d..f3ea9434f71 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 +include::../execution.asciidoc[] -["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. - -[[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 1c780093115..743eb3da0a8 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 +include::../execution.asciidoc[] -["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. - -[[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 fc4f4c0ec60..4dfb11e196d 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 e564494d7f7..4046a6fced1 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>>