Skip to content

Docs: Cut down on high level rest client copy-and-paste-ness #34125

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Sep 28, 2018
Merged

Docs: Cut down on high level rest client copy-and-paste-ness #34125

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
991c1a6
Anchors
nik9000 Sep 27, 2018
a07f98a
includes
nik9000 Sep 27, 2018
89e60b5
get settings
nik9000 Sep 27, 2018
160a192
more
nik9000 Sep 27, 2018
acbe7c4
More
nik9000 Sep 27, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 2 additions & 16 deletions ...el/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,22 +55,8 @@
import static org.hamcrest.Matchers.notNullValue;

/**
* This class is used to generate the Java Cluster 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}/ClusterClientDocumentationIT.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 Cluster APIs in the high level java client.
* Code wrapped in {@code tag} and {@code end} tags is included in the docs.
*/
public class ClusterClientDocumentationIT extends ESRestHighLevelClientTestCase {

Expand Down
65 changes: 18 additions & 47 deletions docs/java-rest/high-level/cluster/get_settings.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,92 +1,63 @@
[[java-rest-high-cluster-get-settings]]
--
:api: get-settings
:request: ClusterGetSettingsRequest
:response: ClusterGetSettingsResponse
--

[id="{upid}-{api}"]
=== Cluster Get Settings API

The Cluster Get Settings API allows to get the cluster wide settings.

[[java-rest-high-cluster-get-settings-request]]
[id="{upid}-{api}-request"]
==== Cluster Get Settings Request

A `ClusterGetSettingsRequest`:
A +{request}+:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request]
include-tagged::{doc-tests-file}[{api}-request]
--------------------------------------------------

==== Optional arguments
The following arguments can optionally be provided:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-includeDefaults]
include-tagged::{doc-tests-file}[{api}-request-includeDefaults]
--------------------------------------------------
<1> By default only those settings that were explicitly set are returned. Setting this to true also returns
the default settings.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-local]
include-tagged::{doc-tests-file}[{api}-request-local]
--------------------------------------------------
<1> By default the request goes to the master of the cluster to get the latest results. If local is specified it gets
the results from whichever node the request goes to.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-masterTimeout]
include-tagged::{doc-tests-file}[{api}-request-masterTimeout]
--------------------------------------------------
<1> Timeout to connect to the master node as a `TimeValue`
<2> Timeout to connect to the master node as a `String`

[[java-rest-high-cluster-get-settings-sync]]
==== Synchronous Execution

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-execute]
--------------------------------------------------
<1> Execute the request and get back the response in a `ClusterGetSettingsResponse` object.

[[java-rest-high-cluster-get-settings-async]]
==== Asynchronous Execution

The asynchronous execution of a cluster get settings requires both the
`ClusterGetSettingsRequest` instance and an `ActionListener` instance to be
passed to the asynchronous method:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-execute-async]
--------------------------------------------------
<1> The `ClusterGetSettingsRequest` 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.
include::../execution.asciidoc[]

A typical listener for `ClusterGetSettingsResponse` looks like:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-execute-listener]
--------------------------------------------------
<1> Called when the execution is successfully completed. The response is
provided as an argument
<2> Called in case of a failure. The raised exception is provided as an argument

[[java-rest-high-cluster-get-settings-response]]
[id="{upid}-{api}-response"]
==== Cluster Get Settings Response

The returned `ClusterGetSettingsResponse` allows to retrieve information about the
The returned +{response}+ allows to retrieve information about the
executed operation as follows:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-response]
include-tagged::{doc-tests-file}[{api}-response]
--------------------------------------------------
<1> Get the persistent settings.
<2> Get the transient settings.
<3> Get the default settings (returns empty settings if `includeDefaults` was not set to `true`).
<4> Get the value as a `String` for a particular setting. The order of searching is first in `persistentSettings` then in
`transientSettings` and finally, if not found in either, in `defaultSettings`.

97 changes: 34 additions & 63 deletions docs/java-rest/high-level/cluster/health.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,22 @@
[[java-rest-high-cluster-health]]
--
:api: health
:request: ClusterHealthRequest
:response: ClusterHealthResponse
--

[id="{upid}-{api}"]
=== Cluster Health API

The Cluster Health API allows getting cluster health.

[[java-rest-high-cluster-health-request]]
[id="{upid}-{api}-request"]
==== Cluster Health Request

A `ClusterHealthRequest`:
A +{request}+:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request]
include-tagged::{doc-tests-file}[{api}-request]
--------------------------------------------------
There are no required parameters. By default, the client will check all indices and will not wait
for any events.
Expand All @@ -21,14 +27,14 @@ Indices which should be checked can be passed in the constructor:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-indices-ctr]
include-tagged::{doc-tests-file}[{api}-request-indices-ctr]
--------------------------------------------------

Or using the corresponding setter method:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-indices-setter]
include-tagged::{doc-tests-file}[{api}-request-indices-setter]
--------------------------------------------------

==== Other parameters
Expand All @@ -37,139 +43,104 @@ Other parameters can be passed only through setter methods:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-timeout]
include-tagged::{doc-tests-file}[{api}-request-timeout]
--------------------------------------------------
<1> Timeout for the request as a `TimeValue`. Defaults to 30 seconds
<2> As a `String`

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-master-timeout]
include-tagged::{doc-tests-file}[{api}-request-master-timeout]
--------------------------------------------------
<1> Timeout to connect to the master node as a `TimeValue`. Defaults to the same as `timeout`
<2> As a `String`

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-status]
include-tagged::{doc-tests-file}[{api}-request-wait-status]
--------------------------------------------------
<1> The status to wait (e.g. `green`, `yellow`, or `red`). Accepts a `ClusterHealthStatus` value.
<2> Using predefined method

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-events]
include-tagged::{doc-tests-file}[{api}-request-wait-events]
--------------------------------------------------
<1> The priority of the events to wait for. Accepts a `Priority` value.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-level]
include-tagged::{doc-tests-file}[{api}-request-level]
--------------------------------------------------
<1> The level of detail of the returned health information. Accepts a `ClusterHealthRequest.Level` value.
<1> The level of detail of the returned health information. Accepts a +{request}.Level+ value.
Default value is `cluster`.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-relocation]
include-tagged::{doc-tests-file}[{api}-request-wait-relocation]
--------------------------------------------------
<1> Wait for 0 relocating shards. Defaults to `false`

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-initializing]
include-tagged::{doc-tests-file}[{api}-request-wait-initializing]
--------------------------------------------------
<1> Wait for 0 initializing shards. Defaults to `false`

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-nodes]
include-tagged::{doc-tests-file}[{api}-request-wait-nodes]
--------------------------------------------------
<1> Wait for `N` nodes in the cluster. Defaults to `0`
<2> Using `>=N`, `<=N`, `>N` and `<N` notation
<3> Using `ge(N)`, `le(N)`, `gt(N)`, `lt(N)` notation

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-active]
include-tagged::{doc-tests-file}[{api}-request-wait-active]
--------------------------------------------------

<1> Wait for all shards to be active in the cluster
<2> Wait for `N` shards to be active in the cluster

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-local]
include-tagged::{doc-tests-file}[{api}-request-local]
--------------------------------------------------
<1> Non-master node can be used for this request. Defaults to `false`

[[java-rest-high-cluster-health-sync]]
==== Synchronous Execution

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute]
--------------------------------------------------

[[java-rest-high-cluster-health-async]]
==== Asynchronous Execution

The asynchronous execution of a cluster health request requires both the
`ClusterHealthRequest` instance and an `ActionListener` instance to be
passed to the asynchronous method:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute-async]
--------------------------------------------------
<1> The `ClusterHealthRequest` 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 `ClusterHealthResponse` looks like:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute-listener]
--------------------------------------------------
<1> Called when the execution is successfully completed. The response is
provided as an argument
<2> Called in case of a failure. The raised exception is provided as an argument
include::../execution.asciidoc[]

[[java-rest-high-cluster-health-response]]
[id="{upid}-{api}-response"]
==== Cluster Health Response

The returned `ClusterHealthResponse` contains the next information about the
The returned +{response}+ contains the next information about the
cluster:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-general]
include-tagged::{doc-tests-file}[{api}-response-general]
--------------------------------------------------
<1> Name of the cluster
<2> Cluster status (`green`, `yellow` or `red`)

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-request-status]
include-tagged::{doc-tests-file}[{api}-response-request-status]
--------------------------------------------------
<1> Whether request was timed out while processing
<2> Status of the request (`OK` or `REQUEST_TIMEOUT`). Other errors will be thrown as exceptions

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-nodes]
include-tagged::{doc-tests-file}[{api}-response-nodes]
--------------------------------------------------
<1> Number of nodes in the cluster
<2> Number of data nodes in the cluster

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-shards]
include-tagged::{doc-tests-file}[{api}-response-shards]
--------------------------------------------------
<1> Number of active shards
<2> Number of primary active shards
Expand All @@ -181,26 +152,26 @@ include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-sh

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-task]
include-tagged::{doc-tests-file}[{api}-response-task]
--------------------------------------------------
<1> Maximum wait time of all tasks in the queue
<2> Number of currently pending tasks
<3> Number of async fetches that are currently ongoing

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-indices]
include-tagged::{doc-tests-file}[{api}-response-indices]
--------------------------------------------------
<1> Detailed information about indices in the cluster

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-index]
include-tagged::{doc-tests-file}[{api}-response-index]
--------------------------------------------------
<1> Detailed information about a specific index

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-shard-details]
include-tagged::{doc-tests-file}[{api}-response-shard-details]
--------------------------------------------------
<1> Detailed information about a specific shard
Loading