From 5fcd52fa18673c4ed3f9d28aaec150846a523459 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Wed, 14 Mar 2018 13:25:10 -0400 Subject: [PATCH] Docs: HighLevelRestClient#ping Add documentation for `HighLevelRestClient#ping`. Relates to #28389 --- ...java => MiscellaneousDocumentationIT.java} | 24 +++++++++---------- .../high-level/getting-started.asciidoc | 4 ++-- docs/java-rest/high-level/migration.asciidoc | 6 ++--- .../high-level/miscellaneous/main.asciidoc | 4 ++-- .../high-level/miscellaneous/ping.asciidoc | 13 ++++++++++ .../high-level/supported-apis.asciidoc | 2 ++ 6 files changed, 32 insertions(+), 21 deletions(-) rename client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/{MainDocumentationIT.java => MiscellaneousDocumentationIT.java} (81%) create mode 100644 docs/java-rest/high-level/miscellaneous/ping.asciidoc diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MainDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java similarity index 81% rename from client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MainDocumentationIT.java rename to client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java index 72986d44f97cd..504ea797c35f6 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MainDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java @@ -31,20 +31,10 @@ import java.io.IOException; /** - * This class is used to generate the Java Main 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}/MainDocumentationIT.java[example] - * -------------------------------------------------- + * Documentation for miscellaneous APIs in the high level java client. + * Code wrapped in {@code tag} and {@code end} tags is included in the docs. */ -public class MainDocumentationIT extends ESRestHighLevelClientTestCase { +public class MiscellaneousDocumentationIT extends ESRestHighLevelClientTestCase { public void testMain() throws IOException { RestHighLevelClient client = highLevelClient(); @@ -67,6 +57,14 @@ public void testMain() throws IOException { } } + public void testPing() throws IOException { + RestHighLevelClient client = highLevelClient(); + //tag::ping-execute + boolean response = client.ping(); + //end::ping-execute + assertTrue(response); + } + public void testInitializationFromClientBuilder() throws IOException { //tag::rest-high-level-client-init RestHighLevelClient client = new RestHighLevelClient( diff --git a/docs/java-rest/high-level/getting-started.asciidoc b/docs/java-rest/high-level/getting-started.asciidoc index ba5c7ba273eec..14a5058eb7272 100644 --- a/docs/java-rest/high-level/getting-started.asciidoc +++ b/docs/java-rest/high-level/getting-started.asciidoc @@ -126,7 +126,7 @@ to be built as follows: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/MainDocumentationIT.java[rest-high-level-client-init] +include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[rest-high-level-client-init] -------------------------------------------------- The high-level client will internally create the low-level client used to @@ -139,7 +139,7 @@ method, which will close the internal `RestClient` instance. ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/MainDocumentationIT.java[rest-high-level-client-close] +include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[rest-high-level-client-close] -------------------------------------------------- In the rest of this documentation about the Java High Level Client, the `RestHighLevelClient` instance diff --git a/docs/java-rest/high-level/migration.asciidoc b/docs/java-rest/high-level/migration.asciidoc index 44e895c9c712e..1349ccb35fe3b 100644 --- a/docs/java-rest/high-level/migration.asciidoc +++ b/docs/java-rest/high-level/migration.asciidoc @@ -64,7 +64,7 @@ argument: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/MainDocumentationIT.java[rest-high-level-client-init] +include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[rest-high-level-client-init] -------------------------------------------------- NOTE: The `RestClient` uses Elasticsearch's HTTP service which is @@ -91,7 +91,7 @@ must be replaced with: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/MainDocumentationIT.java[rest-high-level-client-close] +include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[rest-high-level-client-close] -------------------------------------------------- === Changing the application's code @@ -351,5 +351,3 @@ body, but any other JSON parser could have been use instead. We love to hear from you! Please give us your feedback about your migration experience and how to improve the Java High Level Rest Client on https://discuss.elastic.co/[our forum]. - - diff --git a/docs/java-rest/high-level/miscellaneous/main.asciidoc b/docs/java-rest/high-level/miscellaneous/main.asciidoc index b37e85ee8bd7b..eddbf4a3d0b73 100644 --- a/docs/java-rest/high-level/miscellaneous/main.asciidoc +++ b/docs/java-rest/high-level/miscellaneous/main.asciidoc @@ -8,7 +8,7 @@ Cluster information can be retrieved using the `info()` method: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/MainDocumentationIT.java[main-execute] +include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[main-execute] -------------------------------------------------- [[java-rest-high-main-response]] @@ -18,7 +18,7 @@ The returned `MainResponse` provides various kinds of information about the clus ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -include-tagged::{doc-tests}/MainDocumentationIT.java[main-response] +include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[main-response] -------------------------------------------------- <1> Retrieve the name of the cluster as a `ClusterName` <2> Retrieve the unique identifier of the cluster diff --git a/docs/java-rest/high-level/miscellaneous/ping.asciidoc b/docs/java-rest/high-level/miscellaneous/ping.asciidoc new file mode 100644 index 0000000000000..6cff46a62c5eb --- /dev/null +++ b/docs/java-rest/high-level/miscellaneous/ping.asciidoc @@ -0,0 +1,13 @@ +[[java-rest-high-ping]] +=== Ping API + +[[java-rest-high-ping-request]] +==== Execution + +The `ping()` method checks if the cluster is up and available to +process requests and returns a boolean: + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[ping-execute] +-------------------------------------------------- diff --git a/docs/java-rest/high-level/supported-apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc index 9fb8bd8c66700..fa2f57069ba93 100644 --- a/docs/java-rest/high-level/supported-apis.asciidoc +++ b/docs/java-rest/high-level/supported-apis.asciidoc @@ -37,8 +37,10 @@ include::search/scroll.asciidoc[] The Java High Level REST Client supports the following Miscellaneous APIs: * <> +* <> include::miscellaneous/main.asciidoc[] +include::miscellaneous/ping.asciidoc[] == Indices APIs