HLRC: DRY up remaining CRUD docs (#34925)

This further applies the pattern set in #34125 to reduce copy-and-paste in the multi-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.
elastic · Oct 29, 2018 · e3852f2 · e3852f2
1 parent 71704fa
commit e3852f2
Show file tree

Hide file tree

Showing 8 changed files with 306 additions and 421 deletions.
diff --git a/buildSrc/src/main/resources/checkstyle_suppressions.xml b/buildSrc/src/main/resources/checkstyle_suppressions.xml
@@ -25,7 +25,6 @@
     Truly temporary suppressions suppression of snippets included in
     documentation that are so wide that they scroll.
   -->
-  <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]CRUDDocumentationIT.java" id="SnippetLength" />
   <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]ClusterClientDocumentationIT.java" id="SnippetLength" />
   <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]GraphDocumentationIT.java" id="SnippetLength" />
   <suppress files="client[/\\]rest-high-level[/\\]src[/\\]test[/\\]java[/\\]org[/\\]elasticsearch[/\\]client[/\\]documentation[/\\]IndicesClientDocumentationIT.java" id="SnippetLength" />

diff --git a/...-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java b/...-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java
diff --git a/docs/java-rest/high-level/document/bulk.asciidoc b/docs/java-rest/high-level/document/bulk.asciidoc
@@ -1,38 +1,45 @@
-[[java-rest-high-document-bulk]]
+--
+:api: bulk
+:request: BulkRequest
+:response: BulkResponse
+--
+
+[id="{upid}-{api}"]
 === Bulk API
 
-NOTE: The Java High Level REST Client provides the <<java-rest-high-document-bulk-processor>> to assist with bulk requests
+NOTE: The Java High Level REST Client provides the
+<<{upid}-{api}-processor>> to assist with bulk requests.
 
-[[java-rest-high-document-bulk-request]]
+[id="{upid}-{api}-request"]
 ==== Bulk Request
 
-A `BulkRequest` can be used to execute multiple index, update and/or delete
+A +{request}+ can be used to execute multiple index, update and/or delete
 operations using a single request.
 
 It requires at least one operation to be added to the Bulk request:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
-<1> Creates the `BulkRequest`
-<2> Adds a first `IndexRequest` to the Bulk request. See <<java-rest-high-document-index>>
-for more information on how to build `IndexRequest`.
+<1> Creates the +{request}+
+<2> Adds a first `IndexRequest` to the Bulk request. See <<{upid}-index>> for
+more information on how to build `IndexRequest`.
 <3> Adds a second `IndexRequest`
 <4> Adds a third `IndexRequest`
 
-WARNING: The Bulk API supports only documents encoded in JSON or SMILE. Providing documents
- in any other format will result in an error.
+WARNING: The Bulk API supports only documents encoded in JSON or SMILE.
+Providing documents in any other format will result in an error.
 
-And different operation types can be added to the same `BulkRequest`:
+And different operation types can be added to the same +{request}+:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-with-mixed-operations]
+include-tagged::{doc-tests-file}[{api}-request-with-mixed-operations]
 --------------------------------------------------
-<1> Adds a `DeleteRequest` to the `BulkRequest`. See <<java-rest-high-document-delete>>
+<1> Adds a `DeleteRequest` to the `BulkRequest`. See <<{upid}-delete>>
 for more information on how to build `DeleteRequest`.
-<2> Adds an `UpdateRequest` to the `BulkRequest`. See <<java-rest-high-document-update>>
+<2> Adds an `UpdateRequest` to the `BulkRequest`. See <<{upid}-update>>
 for more information on how to build `UpdateRequest`.
 <3> Adds an `IndexRequest` using the SMILE format
 
@@ -41,102 +48,66 @@ The following arguments can optionally be provided:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-request-timeout]
+include-tagged::{doc-tests-file}[{api}-request-timeout]
 --------------------------------------------------
 <1> Timeout to wait for the bulk request to be performed as a `TimeValue`
 <2> Timeout to wait for the bulk request to be performed as a `String`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-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[bulk-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 index/update/delete operations.
-<2> Number of shard copies provided as a `ActiveShardCount`: can be `ActiveShardCount.ALL`,
-`ActiveShardCount.ONE` or `ActiveShardCount.DEFAULT` (default)
-
-
-[[java-rest-high-document-bulk-sync]]
-==== Synchronous Execution
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute]
---------------------------------------------------
-
-[[java-rest-high-document-bulk-async]]
-==== Asynchronous Execution
+<2> Number of shard copies provided as a `ActiveShardCount`: can be
+`ActiveShardCount.ALL`, `ActiveShardCount.ONE` or
+`ActiveShardCount.DEFAULT` (default)
 
-The asynchronous execution of a bulk request requires both the `BulkRequest`
-instance and an `ActionListener` instance to be passed to the asynchronous
-method:
+include::../execution.asciidoc[]
 
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute-async]
---------------------------------------------------
-<1> The `BulkRequest` 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 `BulkResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-execute-listener]
---------------------------------------------------
-<1> Called when the execution is successfully completed. The response is
-provided as an argument and contains a list of individual results for each
-operation that was executed. Note that one or more operations might have
-failed while the others have been successfully executed.
-<2> Called when the whole `BulkRequest` fails. In this case the raised
-exception is provided as an argument and no operation has been executed.
-
-[[java-rest-high-document-bulk-response]]
+[id="{upid}-{api}-response"]
 ==== Bulk Response
 
-The returned `BulkResponse` contains information about the executed operations and
+The returned +{response}+ contains information about the executed operations and
  allows to iterate over each result as follows:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> Iterate over the results of all operations
-<2> Retrieve the response of the operation (successful or not), can be `IndexResponse`,
-`UpdateResponse` or `DeleteResponse` which can all be seen as `DocWriteResponse` instances
+<2> Retrieve the response of the operation (successful or not), can be
+`IndexResponse`, `UpdateResponse` or `DeleteResponse` which can all be seen as
+`DocWriteResponse` instances
 <3> Handle the response of an index operation
 <4> Handle the response of a update operation
 <5> Handle the response of a delete operation
 
-The Bulk response provides a method to quickly check if one or more operation has failed:
+The Bulk response provides a method to quickly check if one or more operation
+has failed:
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-has-failures]
+include-tagged::{doc-tests-file}[{api}-has-failures]
 --------------------------------------------------
 <1> This method returns `true` if at least one operation failed
 
-In such situation it is necessary to iterate over all operation results in order to check
- if the operation failed, and if so, retrieve the corresponding failure:
+In such situation it is necessary to iterate over all operation results in order
+to check if the operation failed, and if so, retrieve the corresponding failure:
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-errors]
+include-tagged::{doc-tests-file}[{api}-errors]
 --------------------------------------------------
 <1> Indicate if a given operation failed
 <2> Retrieve the failure of the failed operation
 
-[[java-rest-high-document-bulk-processor]]
+[id="{upid}-{api}-processor"]
 ==== Bulk Processor
 
 The `BulkProcessor` simplifies the usage of the Bulk API by providing
@@ -146,29 +117,30 @@ transparently executed as they are added to the processor.
 In order to execute the requests, the `BulkProcessor` requires the following
 components:
 
-`RestHighLevelClient`:: This client is used to execute the `BulkRequest`
+`RestHighLevelClient`:: This client is used to execute the +{request}+
 and to retrieve the `BulkResponse`
 `BulkProcessor.Listener`:: This listener is called before and after
-every `BulkRequest` execution or when a `BulkRequest` failed
+every +{request}+ execution or when a +{request}+ failed
 
-Then the `BulkProcessor.builder` method can be used to build a new `BulkProcessor`:
+Then the `BulkProcessor.builder` method can be used to build a new
+`BulkProcessor`:
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-init]
+include-tagged::{doc-tests-file}[{api}-processor-init]
 --------------------------------------------------
 <1> Create the `BulkProcessor.Listener`
-<2> This method is called before each execution of a `BulkRequest`
-<3> This method is called after each execution of a `BulkRequest`
-<4> This method is called when a `BulkRequest` failed
+<2> This method is called before each execution of a +{request}+
+<3> This method is called after each execution of a +{request}+
+<4> This method is called when a +{request}+ failed
 <5> Create the `BulkProcessor` by calling the `build()` method from
 the `BulkProcessor.Builder`. The `RestHighLevelClient.bulkAsync()`
-method will be used to execute the `BulkRequest` under the hood.
+method will be used to execute the +{request}+ under the hood.
 
-The `BulkProcessor.Builder` provides methods to configure how the `BulkProcessor`
-should handle requests execution:
+The `BulkProcessor.Builder` provides methods to configure how the
+`BulkProcessor` should handle requests execution:
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-options]
+include-tagged::{doc-tests-file}[{api}-processor-options]
 --------------------------------------------------
 <1> Set when to flush a new bulk request based on the number of
 actions currently added (defaults to 1000, use -1 to disable it)
@@ -186,42 +158,41 @@ for more options.
 Once the `BulkProcessor` is created requests can be added to it:
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-add]
+include-tagged::{doc-tests-file}[{api}-processor-add]
 --------------------------------------------------
 
 The requests will be executed by the `BulkProcessor`, which takes care of
 calling the `BulkProcessor.Listener` for every bulk request.
 
-The listener provides methods to access to the `BulkRequest` and the `BulkResponse`:
+The listener provides methods to access to the +{request}+ and the +{response}+:
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-listener]
+include-tagged::{doc-tests-file}[{api}-processor-listener]
 --------------------------------------------------
-<1> Called before each execution of a `BulkRequest`, this method allows
-to know the number of operations that are going to be executed within the `BulkRequest`
-<2> Called after each execution of a `BulkRequest`, this method allows
-to know if the `BulkResponse` contains errors
-<3> Called if the `BulkRequest` failed, this method allows to know
+<1> Called before each execution of a +{request}+, this method allows to know
+the number of operations that are going to be executed within the +{request}+
+<2> Called after each execution of a +{request}+, this method allows to know if
+the +{response}+ contains errors
+<3> Called if the +{request}+ failed, this method allows to know
 the failure
 
 Once all requests have been added to the `BulkProcessor`, its instance needs to
 be closed using one of the two available closing methods.
 
-The `awaitClose()` method can be used to wait until all requests have been processed
- or the specified waiting time elapses:
+The `awaitClose()` method can be used to wait until all requests have been
+processed or the specified waiting time elapses:
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-await]
+include-tagged::{doc-tests-file}[{api}-processor-await]
 --------------------------------------------------
 <1> The method returns `true` if all bulk requests completed and `false` if the
 waiting time elapsed before all the bulk requests completed
 
 The `close()` method can be used to immediately close the `BulkProcessor`:
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/CRUDDocumentationIT.java[bulk-processor-close]
+include-tagged::{doc-tests-file}[{api}-processor-close]
 --------------------------------------------------
 
-Both methods flush the requests added to the processor before closing the processor
-and also forbid any new request to be added to it.
-
+Both methods flush the requests added to the processor before closing the
+processor and also forbid any new request to be added to it.