Skip to content

Commit a21cd2a

Browse files
nik9000nik9000
committed
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.
1 parent 696a965 commit a21cd2a

File tree

7 files changed

+136
-237
lines changed

7 files changed

+136
-237
lines changed

‎client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java‎

Lines changed: 33 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,8 @@ public void testIndex() throws Exception {
176176
// <3>
177177
}
178178
if (shardInfo.getFailed() > 0) {
179-
for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) {
179+
for (ReplicationResponse.ShardInfo.Failure failure :
180+
shardInfo.getFailures()) {
180181
String reason = failure.reason(); // <4>
181182
}
182183
}
@@ -242,8 +243,9 @@ public void testIndex() throws Exception {
242243
}
243244
{
244245
IndexRequest request = new IndexRequest("posts", "doc", "async").source("field", "value");
246+
ActionListener<IndexResponse> listener;
245247
// tag::index-execute-listener
246-
ActionListener<IndexResponse> listener = new ActionListener<IndexResponse>() {
248+
listener = new ActionListener<IndexResponse>() {
247249
@Override
248250
public void onResponse(IndexResponse indexResponse) {
249251
// <1>
@@ -307,8 +309,8 @@ public void testUpdate() throws Exception {
307309

308310
request = new UpdateRequest("posts", "doc", "1").fetchSource(true);
309311
//tag::update-request-with-stored-script
310-
Script stored =
311-
new Script(ScriptType.STORED, null, "increment-field", parameters); // <1>
312+
Script stored = new Script(
313+
ScriptType.STORED, null, "increment-field", parameters); // <1>
312314
request.script(stored); // <2>
313315
//end::update-request-with-stored-script
314316
updateResponse = client.update(request, RequestOptions.DEFAULT);
@@ -361,7 +363,8 @@ public void testUpdate() throws Exception {
361363
//end::update-request-with-doc-as-string
362364
request.fetchSource(true);
363365
// tag::update-execute
364-
UpdateResponse updateResponse = client.update(request, RequestOptions.DEFAULT);
366+
UpdateResponse updateResponse = client.update(
367+
request, RequestOptions.DEFAULT);
365368
// end::update-execute
366369
assertEquals(DocWriteResponse.Result.UPDATED, updateResponse.getResult());
367370

@@ -399,7 +402,8 @@ public void testUpdate() throws Exception {
399402
// <1>
400403
}
401404
if (shardInfo.getFailed() > 0) {
402-
for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) {
405+
for (ReplicationResponse.ShardInfo.Failure failure :
406+
shardInfo.getFailures()) {
403407
String reason = failure.reason(); // <2>
404408
}
405409
}
@@ -410,7 +414,8 @@ public void testUpdate() throws Exception {
410414
UpdateRequest request = new UpdateRequest("posts", "type", "does_not_exist")
411415
.doc("field", "value");
412416
try {
413-
UpdateResponse updateResponse = client.update(request, RequestOptions.DEFAULT);
417+
UpdateResponse updateResponse = client.update(
418+
request, RequestOptions.DEFAULT);
414419
} catch (ElasticsearchException e) {
415420
if (e.status() == RestStatus.NOT_FOUND) {
416421
// <1>
@@ -424,7 +429,8 @@ public void testUpdate() throws Exception {
424429
.doc("field", "value")
425430
.version(1);
426431
try {
427-
UpdateResponse updateResponse = client.update(request, RequestOptions.DEFAULT);
432+
UpdateResponse updateResponse = client.update(
433+
request, RequestOptions.DEFAULT);
428434
} catch(ElasticsearchException e) {
429435
if (e.status() == RestStatus.CONFLICT) {
430436
// <1>
@@ -447,7 +453,8 @@ public void testUpdate() throws Exception {
447453
//tag::update-request-source-include
448454
String[] includes = new String[]{"updated", "r*"};
449455
String[] excludes = Strings.EMPTY_ARRAY;
450-
request.fetchSource(new FetchSourceContext(true, includes, excludes)); // <1>
456+
request.fetchSource(
457+
new FetchSourceContext(true, includes, excludes)); // <1>
451458
//end::update-request-source-include
452459
UpdateResponse updateResponse = client.update(request, RequestOptions.DEFAULT);
453460
assertEquals(DocWriteResponse.Result.UPDATED, updateResponse.getResult());
@@ -461,7 +468,8 @@ public void testUpdate() throws Exception {
461468
//tag::update-request-source-exclude
462469
String[] includes = Strings.EMPTY_ARRAY;
463470
String[] excludes = new String[]{"updated"};
464-
request.fetchSource(new FetchSourceContext(true, includes, excludes)); // <1>
471+
request.fetchSource(
472+
new FetchSourceContext(true, includes, excludes)); // <1>
465473
//end::update-request-source-exclude
466474
UpdateResponse updateResponse = client.update(request, RequestOptions.DEFAULT);
467475
assertEquals(DocWriteResponse.Result.UPDATED, updateResponse.getResult());
@@ -513,8 +521,9 @@ public void testUpdate() throws Exception {
513521
{
514522
UpdateRequest request = new UpdateRequest("posts", "doc", "async").doc("reason", "async update").docAsUpsert(true);
515523

524+
ActionListener<UpdateResponse> listener;
516525
// tag::update-execute-listener
517-
ActionListener<UpdateResponse> listener = new ActionListener<UpdateResponse>() {
526+
listener = new ActionListener<UpdateResponse>() {
518527
@Override
519528
public void onResponse(UpdateResponse updateResponse) {
520529
// <1>
@@ -552,12 +561,13 @@ public void testDelete() throws Exception {
552561
// tag::delete-request
553562
DeleteRequest request = new DeleteRequest(
554563
"posts", // <1>
555-
"doc", // <2>
556-
"1"); // <3>
564+
"doc", // <2>
565+
"1"); // <3>
557566
// end::delete-request
558567

559568
// tag::delete-execute
560-
DeleteResponse deleteResponse = client.delete(request, RequestOptions.DEFAULT);
569+
DeleteResponse deleteResponse = client.delete(
570+
request, RequestOptions.DEFAULT);
561571
// end::delete-execute
562572
assertSame(DocWriteResponse.Result.DELETED, deleteResponse.getResult());
563573

@@ -571,7 +581,8 @@ public void testDelete() throws Exception {
571581
// <1>
572582
}
573583
if (shardInfo.getFailed() > 0) {
574-
for (ReplicationResponse.ShardInfo.Failure failure : shardInfo.getFailures()) {
584+
for (ReplicationResponse.ShardInfo.Failure failure :
585+
shardInfo.getFailures()) {
575586
String reason = failure.reason(); // <2>
576587
}
577588
}
@@ -605,7 +616,8 @@ public void testDelete() throws Exception {
605616
{
606617
// tag::delete-notfound
607618
DeleteRequest request = new DeleteRequest("posts", "doc", "does_not_exist");
608-
DeleteResponse deleteResponse = client.delete(request, RequestOptions.DEFAULT);
619+
DeleteResponse deleteResponse = client.delete(
620+
request, RequestOptions.DEFAULT);
609621
if (deleteResponse.getResult() == DocWriteResponse.Result.NOT_FOUND) {
610622
// <1>
611623
}
@@ -619,8 +631,9 @@ public void testDelete() throws Exception {
619631

620632
// tag::delete-conflict
621633
try {
622-
DeleteRequest request = new DeleteRequest("posts", "doc", "1").version(2);
623-
DeleteResponse deleteResponse = client.delete(request, RequestOptions.DEFAULT);
634+
DeleteResponse deleteResponse = client.delete(
635+
new DeleteRequest("posts", "doc", "1").version(2),
636+
RequestOptions.DEFAULT);
624637
} catch (ElasticsearchException exception) {
625638
if (exception.status() == RestStatus.CONFLICT) {
626639
// <1>
@@ -635,8 +648,9 @@ public void testDelete() throws Exception {
635648

636649
DeleteRequest request = new DeleteRequest("posts", "doc", "async");
637650

651+
ActionListener<DeleteResponse> listener;
638652
// tag::delete-execute-listener
639-
ActionListener<DeleteResponse> listener = new ActionListener<DeleteResponse>() {
653+
listener = new ActionListener<DeleteResponse>() {
640654
@Override
641655
public void onResponse(DeleteResponse deleteResponse) {
642656
// <1>

‎docs/java-rest/high-level/document/delete.asciidoc‎

Lines changed: 22 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,20 @@
1-
[[java-rest-high-document-delete]]
1+
--
2+
:api: delete
3+
:request: DeleteRequest
4+
:response: DeleteResponse
5+
--
6+
7+
[id="{upid}-{api}"]
28
=== Delete API
39

4-
[[java-rest-high-document-delete-request]]
10+
[id="{upid}-{api}-request"]
511
==== Delete Request
612

7-
A `DeleteRequest` requires the following arguments:
13+
A +{request}+ requires the following arguments:
814

915
["source","java",subs="attributes,callouts,macros"]
1016
--------------------------------------------------
11-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request]
17+
include-tagged::{doc-tests-file}[{api}-request]
1218
--------------------------------------------------
1319
<1> Index
1420
<2> Type
@@ -19,88 +25,53 @@ The following arguments can optionally be provided:
1925

2026
["source","java",subs="attributes,callouts,macros"]
2127
--------------------------------------------------
22-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-routing]
28+
include-tagged::{doc-tests-file}[{api}-request-routing]
2329
--------------------------------------------------
2430
<1> Routing value
2531

2632
["source","java",subs="attributes,callouts,macros"]
2733
--------------------------------------------------
28-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-parent]
34+
include-tagged::{doc-tests-file}[{api}-request-parent]
2935
--------------------------------------------------
3036
<1> Parent value
3137

3238
["source","java",subs="attributes,callouts,macros"]
3339
--------------------------------------------------
34-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-timeout]
40+
include-tagged::{doc-tests-file}[{api}-request-timeout]
3541
--------------------------------------------------
3642
<1> Timeout to wait for primary shard to become available as a `TimeValue`
3743
<2> Timeout to wait for primary shard to become available as a `String`
3844

3945
["source","java",subs="attributes,callouts,macros"]
4046
--------------------------------------------------
41-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-refresh]
47+
include-tagged::{doc-tests-file}[{api}-request-refresh]
4248
--------------------------------------------------
4349
<1> Refresh policy as a `WriteRequest.RefreshPolicy` instance
4450
<2> Refresh policy as a `String`
4551

4652
["source","java",subs="attributes,callouts,macros"]
4753
--------------------------------------------------
48-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-version]
54+
include-tagged::{doc-tests-file}[{api}-request-version]
4955
--------------------------------------------------
5056
<1> Version
5157

5258
["source","java",subs="attributes,callouts,macros"]
5359
--------------------------------------------------
54-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-version-type]
60+
include-tagged::{doc-tests-file}[{api}-request-version-type]
5561
--------------------------------------------------
5662
<1> Version type
5763

58-
[[java-rest-high-document-delete-sync]]
59-
==== Synchronous Execution
60-
61-
["source","java",subs="attributes,callouts,macros"]
62-
--------------------------------------------------
63-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute]
64-
--------------------------------------------------
65-
66-
[[java-rest-high-document-delete-async]]
67-
==== Asynchronous Execution
68-
69-
The asynchronous execution of a delete request requires both the `DeleteRequest`
70-
instance and an `ActionListener` instance to be passed to the asynchronous
71-
method:
72-
73-
["source","java",subs="attributes,callouts,macros"]
74-
--------------------------------------------------
75-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute-async]
76-
--------------------------------------------------
77-
<1> The `DeleteRequest` to execute and the `ActionListener` to use when
78-
the execution completes
79-
80-
The asynchronous method does not block and returns immediately. Once it is
81-
completed the `ActionListener` is called back using the `onResponse` method
82-
if the execution successfully completed or using the `onFailure` method if
83-
it failed.
84-
85-
A typical listener for `DeleteResponse` looks like:
86-
87-
["source","java",subs="attributes,callouts,macros"]
88-
--------------------------------------------------
89-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute-listener]
90-
--------------------------------------------------
91-
<1> Called when the execution is successfully completed. The response is
92-
provided as an argument
93-
<2> Called in case of failure. The raised exception is provided as an argument
64+
include::../execution.asciidoc[]
9465

95-
[[java-rest-high-document-delete-response]]
66+
[id="{upid}-{api}-response"]
9667
==== Delete Response
9768

98-
The returned `DeleteResponse` allows to retrieve information about the executed
69+
The returned +{response}+ allows to retrieve information about the executed
9970
operation as follows:
10071

10172
["source","java",subs="attributes,callouts,macros"]
10273
--------------------------------------------------
103-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-response]
74+
include-tagged::{doc-tests-file}[{api}-response]
10475
--------------------------------------------------
10576
<1> Handle the situation where number of successful shards is less than
10677
total shards
@@ -111,7 +82,7 @@ It is also possible to check whether the document was found or not:
11182

11283
["source","java",subs="attributes,callouts,macros"]
11384
--------------------------------------------------
114-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-notfound]
85+
include-tagged::{doc-tests-file}[{api}-notfound]
11586
--------------------------------------------------
11687
<1> Do something if the document to be deleted was not found
11788

@@ -120,7 +91,7 @@ be thrown:
12091

12192
["source","java",subs="attributes,callouts,macros"]
12293
--------------------------------------------------
123-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-conflict]
94+
include-tagged::{doc-tests-file}[{api}-conflict]
12495
--------------------------------------------------
12596
<1> The raised exception indicates that a version conflict error was returned
12697

‎docs/java-rest/high-level/document/exists.asciidoc‎

Lines changed: 11 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,31 @@
1-
[[java-rest-high-document-exists]]
1+
--
2+
:api: exists
3+
:request: GetRequest
4+
:response: boolean
5+
--
6+
7+
[id="{upid}-{api}"]
28
=== Exists API
39

410
The exists API returns `true` if a document exists, and `false` otherwise.
511

6-
[[java-rest-high-document-exists-request]]
12+
[id="{upid}-{api}-request"]
713
==== Exists Request
814

9-
It uses `GetRequest` just like the <<java-rest-high-document-get>>.
15+
It uses +{request}+ just like the <<java-rest-high-document-get>>.
1016
All of its <<java-rest-high-document-get-request-optional-arguments, optional arguments>>
1117
are supported. Since `exists()` only returns `true` or `false`, we recommend
1218
turning off fetching `_source` and any stored fields so the request is
1319
slightly lighter:
1420

1521
["source","java",subs="attributes,callouts,macros"]
1622
--------------------------------------------------
17-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-request]
23+
include-tagged::{doc-tests-file}[{api}-request]
1824
--------------------------------------------------
1925
<1> Index
2026
<2> Type
2127
<3> Document id
2228
<4> Disable fetching `_source`.
2329
<5> Disable fetching stored fields.
2430

25-
[[java-rest-high-document-exists-sync]]
26-
==== Synchronous Execution
27-
28-
["source","java",subs="attributes,callouts,macros"]
29-
--------------------------------------------------
30-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-execute]
31-
--------------------------------------------------
32-
33-
[[java-rest-high-document-exists-async]]
34-
==== Asynchronous Execution
35-
36-
The asynchronous execution of exists request requires both the `GetRequest`
37-
instance and an `ActionListener` instance to be passed to the asynchronous
38-
method:
39-
40-
["source","java",subs="attributes,callouts,macros"]
41-
--------------------------------------------------
42-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-execute-async]
43-
--------------------------------------------------
44-
<1> The `GetRequest` to execute and the `ActionListener` to use when
45-
the execution completes.
46-
47-
The asynchronous method does not block and returns immediately. Once it is
48-
completed the `ActionListener` is called back using the `onResponse` method
49-
if the execution successfully completed or using the `onFailure` method if
50-
it failed.
51-
52-
A typical listener for `GetResponse` looks like:
53-
54-
["source","java",subs="attributes,callouts,macros"]
55-
--------------------------------------------------
56-
include-tagged::{doc-tests}/CRUDDocumentationIT.java[exists-execute-listener]
57-
--------------------------------------------------
58-
<1> Called when the execution is successfully completed. The response is
59-
provided as an argument.
60-
<2> Called in case of failure. The raised exception is provided as an argument.
31+
include::../execution.asciidoc[]

0 commit comments

Comments
 (0)