Docs: DRY up CRUD docs (#34203)
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.
This commit is contained in:
Nik Everett
GitHub
parent
e95dc5474f
commit
a9fa5f2b33
|
|
@ -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<IndexResponse> listener;
|
||||
// tag::index-execute-listener
|
||||
ActionListener<IndexResponse> listener = new ActionListener<IndexResponse>() {
|
||||
listener = new ActionListener<IndexResponse>() {
|
||||
@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<UpdateResponse> listener;
|
||||
// tag::update-execute-listener
|
||||
ActionListener<UpdateResponse> listener = new ActionListener<UpdateResponse>() {
|
||||
listener = new ActionListener<UpdateResponse>() {
|
||||
@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<DeleteResponse> listener;
|
||||
// tag::delete-execute-listener
|
||||
ActionListener<DeleteResponse> listener = new ActionListener<DeleteResponse>() {
|
||||
listener = new ActionListener<DeleteResponse>() {
|
||||
@Override
|
||||
public void onResponse(DeleteResponse deleteResponse) {
|
||||
// <1>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <<java-rest-high-document-get>>.
|
||||
It uses +{request}+ 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
|
||||
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -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<String, Object>`
|
||||
<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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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"]
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -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>>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue