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 5dc4c88cbbcc1..7d61ec0f3d97c 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 @@ -95,22 +95,8 @@ import static org.hamcrest.Matchers.not; /** - * This class is used to generate the Java CRUD API documentation. - * You need to wrap your code between two tags like: - * // tag::example - * // end::example - * - * Where example is your tag name. - * - * Then in the documentation, you can extract what is between tag and end tags with - * ["source","java",subs="attributes,callouts,macros"] - * -------------------------------------------------- - * include-tagged::{doc-tests}/CRUDDocumentationIT.java[example] - * -------------------------------------------------- - * - * The column width of the code block is 84. If the code contains a line longer - * than 84, the line will be cut and a horizontal scroll bar will be displayed. - * (the code indentation of the tag is not included in the width) + * Documentation for CRUD APIs in the high level java client. + * Code wrapped in {@code tag} and {@code end} tags is included in the docs. */ public class CRUDDocumentationIT extends ESRestHighLevelClientTestCase { diff --git a/docs/java-rest/high-level/document/index.asciidoc b/docs/java-rest/high-level/document/index.asciidoc index b64e19d1d33eb..c5800e150564c 100644 --- a/docs/java-rest/high-level/document/index.asciidoc +++ b/docs/java-rest/high-level/document/index.asciidoc @@ -1,14 +1,20 @@ -[[java-rest-high-document-index]] +-- +:api: index +:request: IndexRequest +:response: IndexResponse +-- + +[id="{upid}-{api}"] === Index API -[[java-rest-high-document-index-request]] +[id="{upid}-{api}-request"] ==== Index Request -An `IndexRequest` requires the following arguments: +An +{request}+ requires the following arguments: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-string] +include-tagged::{doc-tests-file}[{api}-request-string] -------------------------------------------------- <1> Index <2> Type @@ -21,21 +27,21 @@ The document source can be provided in different ways in addition to the ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-map] +include-tagged::{doc-tests-file}[{api}-request-map] -------------------------------------------------- <1> 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[index-request-xcontent] +include-tagged::{doc-tests-file}[{api}-request-xcontent] -------------------------------------------------- <1> 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[index-request-shortcut] +include-tagged::{doc-tests-file}[{api}-request-shortcut] -------------------------------------------------- <1> Document source provided as `Object` key-pairs, which gets converted to JSON format @@ -45,95 +51,60 @@ The following arguments can optionally be provided: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-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[index-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[index-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[index-request-version] +include-tagged::{doc-tests-file}[{api}-request-version] -------------------------------------------------- <1> Version ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-version-type] +include-tagged::{doc-tests-file}[{api}-request-version-type] -------------------------------------------------- <1> Version type ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-op-type] +include-tagged::{doc-tests-file}[{api}-request-op-type] -------------------------------------------------- <1> Operation type provided as an `DocWriteRequest.OpType` value <2> Operation type provided as a `String`: can be `create` or `update` (default) ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-pipeline] +include-tagged::{doc-tests-file}[{api}-request-pipeline] -------------------------------------------------- <1> The name of the ingest pipeline to be executed before indexing the document -[[java-rest-high-document-index-sync]] -==== Synchronous Execution - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute] --------------------------------------------------- - -[[java-rest-high-document-index-async]] -==== Asynchronous Execution - -The asynchronous execution of an index request requires both the `IndexRequest` -instance and an `ActionListener` instance to be passed to the asynchronous -method: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute-async] --------------------------------------------------- -<1> The `IndexRequest` 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 `IndexResponse` looks like: - -["source","java",subs="attributes,callouts,macros"] --------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute-listener] --------------------------------------------------- -<1> Called when the execution is successfully completed. The response is -provided as an argument -<2> Called in case of failure. The raised exception is provided as an argument +include::../execution.asciidoc[] -[[java-rest-high-document-index-response]] +[id="{upid}-{api}-response"] ==== Index Response -The returned `IndexResponse` 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[index-response] +include-tagged::{doc-tests-file}[{api}-response] -------------------------------------------------- <1> Handle (if needed) the case where the document was created for the first time @@ -148,7 +119,7 @@ be thrown: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-conflict] +include-tagged::{doc-tests-file}[{api}-conflict] -------------------------------------------------- <1> The raised exception indicates that a version conflict error was returned @@ -157,6 +128,6 @@ same index, type and id already existed: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-optype] +include-tagged::{doc-tests-file}[{api}-optype] -------------------------------------------------- <1> The raised exception indicates that a version conflict error was returned diff --git a/docs/java-rest/high-level/supported-apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc index 8e3e8f5812bd4..306506411ee74 100644 --- a/docs/java-rest/high-level/supported-apis.asciidoc +++ b/docs/java-rest/high-level/supported-apis.asciidoc @@ -2,23 +2,26 @@ == Document APIs +:upid: {mainid}-document +:doc-tests-file: {doc-tests}/CRUDDocumentationIT.java + The Java High Level REST Client supports the following Document APIs: [[single-doc]] Single document APIs:: -* <> -* <> -* <> -* <> +* <<{upid}-index>> +* <<{upid}-get>> +* <<{upid}-delete>> +* <<{upid}-update>> [[multi-doc]] Multi-document APIs:: -* <> -* <> -* <> -* <> -* <> -* <> +* <<{upid}-bulk>> +* <<{upid}-multi-get>> +* <<{upid}-reindex>> +* <<{upid}-update-by-query>> +* <<{upid}-delete-by-query>> +* <<{upid}-reindex-rethrottle>> include::document/index.asciidoc[] include::document/get.asciidoc[] @@ -34,20 +37,21 @@ include::document/reindex-rethrottle.asciidoc[] == Search APIs +:upid: {mainid} +:doc-tests-file: {doc-tests}/SearchDocumentationIT.java + The Java High Level REST Client supports the following Search APIs: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* <<{upid}-search>> +* <<{upid}-search-scroll>> +* <<{upid}-clear-scroll>> +* <<{upid}-search-template>> +* <<{upid}-multi-search-template>> +* <<{upid}-multi-search>> +* <<{upid}-field-caps>> +* <<{upid}-rank-eval>> +* <<{upid}-explain>> -:upid: {mainid} -:doc-tests-file: {doc-tests}/SearchDocumentationIT.java include::search/search.asciidoc[] include::search/scroll.asciidoc[] include::search/multi-search.asciidoc[]