[Docs] Add migration notes for the high-level rest client

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

@@ -19,11 +19,9 @@
 
 package org.elasticsearch.client.documentation;
 
-import org.elasticsearch.client.http.HttpEntity;
-import org.elasticsearch.client.http.client.methods.HttpPost;
-import org.elasticsearch.client.http.entity.ContentType;
-import org.elasticsearch.client.http.nio.entity.NStringEntity;
+import org.elasticsearch.Build;
 import org.elasticsearch.ElasticsearchException;
+import org.elasticsearch.Version;
 import org.elasticsearch.action.ActionListener;
 import org.elasticsearch.action.DocWriteRequest;
 import org.elasticsearch.action.DocWriteResponse;
@@ -38,6 +36,7 @@
 import org.elasticsearch.action.get.GetResponse;
 import org.elasticsearch.action.index.IndexRequest;
 import org.elasticsearch.action.index.IndexResponse;
+import org.elasticsearch.action.main.MainResponse;
 import org.elasticsearch.action.support.ActiveShardCount;
 import org.elasticsearch.action.support.WriteRequest;
 import org.elasticsearch.action.support.replication.ReplicationResponse;
@@ -46,6 +45,11 @@
 import org.elasticsearch.client.ESRestHighLevelClientTestCase;
 import org.elasticsearch.client.Response;
 import org.elasticsearch.client.RestHighLevelClient;
+import org.elasticsearch.client.http.HttpEntity;
+import org.elasticsearch.client.http.client.methods.HttpPost;
+import org.elasticsearch.client.http.entity.ContentType;
+import org.elasticsearch.client.http.nio.entity.NStringEntity;
+import org.elasticsearch.cluster.ClusterName;
 import org.elasticsearch.common.Strings;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.unit.ByteSizeUnit;

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

@@ -0,0 +1,68 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.client.documentation;
+
+import org.elasticsearch.Build;
+import org.elasticsearch.Version;
+import org.elasticsearch.action.main.MainResponse;
+import org.elasticsearch.client.ESRestHighLevelClientTestCase;
+import org.elasticsearch.client.RestHighLevelClient;
+import org.elasticsearch.cluster.ClusterName;
+
+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]
+ * --------------------------------------------------
+ */
+public class MainDocumentationIT extends ESRestHighLevelClientTestCase {
+
+    public void testMain() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+        {
+            //tag::main-execute
+            MainResponse response = client.info();
+            //end::main-execute
+            assertTrue(response.isAvailable());
+            //tag::main-response
+            ClusterName clusterName = response.getClusterName(); // <1>
+            String clusterUuid = response.getClusterUuid(); // <2>
+            String nodeName = response.getNodeName(); // <3>
+            Version version = response.getVersion(); // <4>
+            Build build = response.getBuild(); // <5>
+            //end::main-response
+            assertNotNull(clusterName);
+            assertNotNull(clusterUuid);
+            assertNotNull(nodeName);
+            assertNotNull(version);
+            assertNotNull(build);
+        }
+    }
+}

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

@@ -0,0 +1,162 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.client.documentation;
+
+import org.elasticsearch.action.ActionListener;
+import org.elasticsearch.action.delete.DeleteRequest;
+import org.elasticsearch.action.delete.DeleteResponse;
+import org.elasticsearch.action.index.IndexRequest;
+import org.elasticsearch.action.index.IndexRequestBuilder;
+import org.elasticsearch.action.index.IndexResponse;
+import org.elasticsearch.client.ESRestHighLevelClientTestCase;
+import org.elasticsearch.client.Response;
+import org.elasticsearch.client.RestClient;
+import org.elasticsearch.client.RestHighLevelClient;
+import org.elasticsearch.client.http.HttpEntity;
+import org.elasticsearch.client.http.HttpStatus;
+import org.elasticsearch.client.http.entity.ContentType;
+import org.elasticsearch.client.http.nio.entity.NStringEntity;
+import org.elasticsearch.cluster.health.ClusterHealthStatus;
+import org.elasticsearch.common.settings.Settings;
+import org.elasticsearch.common.xcontent.XContentFactory;
+import org.elasticsearch.common.xcontent.XContentHelper;
+import org.elasticsearch.common.xcontent.XContentType;
+import org.elasticsearch.rest.RestStatus;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Map;
+
+import static java.util.Collections.emptyMap;
+import static org.elasticsearch.cluster.metadata.IndexMetaData.SETTING_NUMBER_OF_REPLICAS;
+import static org.elasticsearch.cluster.metadata.IndexMetaData.SETTING_NUMBER_OF_SHARDS;
+
+/**
+ * This class is used to generate the documentation for the
+ * docs/java-rest/high-level/migration.asciidoc page.
+ *
+ * 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}/MigrationDocumentationIT.java[example]
+ * --------------------------------------------------
+ */
+public class MigrationDocumentationIT extends ESRestHighLevelClientTestCase {
+
+    public void testCreateIndex() throws IOException {
+        RestClient restClient = client();
+        {
+            //tag::migration-create-inded
+            Settings indexSettings = Settings.builder() // <1>
+                    .put(SETTING_NUMBER_OF_SHARDS, 1)
+                    .put(SETTING_NUMBER_OF_REPLICAS, 0)
+                    .build();
+
+            String payload = XContentFactory.jsonBuilder() // <2>
+                    .startObject()
+                        .startObject("settings") // <3>
+                            .value(indexSettings)
+                        .endObject()
+                        .startObject("mappings")  // <4>
+                            .startObject("doc")
+                                .startObject("properties")
+                                    .startObject("time")
+                                        .field("type", "date")
+                                    .endObject()
+                                .endObject()
+                            .endObject()
+                        .endObject()
+                    .endObject().string();
+
+            HttpEntity entity = new NStringEntity(payload, ContentType.APPLICATION_JSON); // <5>
+
+            Response response = restClient.performRequest("PUT", "my-index", emptyMap(), entity); // <6>
+            if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
+                // <7>
+            }
+            //end::migration-create-inded
+            assertEquals(200, response.getStatusLine().getStatusCode());
+        }
+    }
+
+    public void testClusterHealth() throws IOException {
+        RestClient restClient = client();
+        {
+            //tag::migration-cluster-health
+            Response response = restClient.performRequest("GET", "/_cluster/health"); // <1>
+
+            ClusterHealthStatus healthStatus;
+            try (InputStream is = response.getEntity().getContent()) { // <2>
+                Map<String, Object> map = XContentHelper.convertToMap(XContentType.JSON.xContent(), is, true); // <3>
+                healthStatus = ClusterHealthStatus.fromString((String) map.get("status")); // <4>
+            }
+
+            if (healthStatus == ClusterHealthStatus.GREEN) {
+                // <5>
+            }
+            //end::migration-cluster-health
+            assertSame(ClusterHealthStatus.GREEN, healthStatus);
+        }
+    }
+
+    public void testRequests() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+        {
+            //tag::migration-request-ctor
+            IndexRequest request = new IndexRequest("index", "doc", "id"); // <1>
+            request.source("{\"field\":\"value\"}", XContentType.JSON);
+            //end::migration-request-ctor
+
+            //tag::migration-request-ctor-execution
+            IndexResponse response = client.index(request);
+            //end::migration-request-ctor-execution
+            assertEquals(RestStatus.CREATED, response.status());
+        }
+        {
+            //tag::migration-request-sync-execution
+            DeleteRequest request = new DeleteRequest("index", "doc", "id");
+            DeleteResponse response = client.delete(request); // <1>
+            //end::migration-request-sync-execution
+            assertEquals(RestStatus.OK, response.status());
+        }
+        {
+            //tag::migration-request-async-execution
+            DeleteRequest request = new DeleteRequest("index", "doc", "id"); // <1>
+            client.deleteAsync(request, new ActionListener<DeleteResponse>() { // <2>
+                @Override
+                public void onResponse(DeleteResponse deleteResponse) {
+                    // <3>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <4>
+                }
+            });
+            //end::migration-request-async-execution
+        }
+    }
+}

docs/java-api/client.asciidoc

@@ -23,6 +23,10 @@ cluster.
 
 ==============================
 
+WARNING: The `TransportClient` is aimed to be replaced by the Java High Level REST
+Client, which executes HTTP requests instead of serialized Java requests. The
+`TransportClient` will be deprecated in upcoming versions of Elasticsearch and it
+is advised to use the Java High Level REST Client instead.
 
 [[transport-client]]
 === Transport Client

docs/java-api/index.asciidoc

@@ -17,6 +17,11 @@ Additionally, operations on a client may be accumulated and executed in
 Note, all the APIs are exposed through the
 Java API (actually, the Java API is used internally to execute them).
 
+WARNING: Starting from version 5.6.0, a new Java client has been
+released: the {java-rest}/java-rest-high.html[Java High Level REST Client].
+This new client is designed to replace the `TransportClient` in Java
+applications which will be deprecated in future versions of Elasticsearch.
+
 == Javadoc
 
 The javadoc for the transport client can be found at {transport-client-javadoc}/index.html.

docs/java-rest/high-level/apis.asciidoc

@@ -1,3 +1,4 @@
+[[java-rest-high-supported-apis]]
 == Supported APIs
 
 The Java High Level REST Client supports the following APIs:
@@ -15,3 +16,6 @@ The Java High Level REST Client supports the following APIs:
 * <<java-rest-high-search>>
 * <<java-rest-high-search-scroll>>
 * <<java-rest-high-clear-scroll>>
+
+.Miscellaneous APIs
+* <<java-rest-high-main>>

docs/java-rest/high-level/apis/index.asciidoc

@@ -1,11 +1,8 @@
-:doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation
-
 include::_index.asciidoc[]
 include::get.asciidoc[]
 include::delete.asciidoc[]
 include::update.asciidoc[]
 include::bulk.asciidoc[]
 include::search.asciidoc[]
 include::scroll.asciidoc[]
-
-:doc-tests!:
+include::main.asciidoc[]

docs/java-rest/high-level/apis/main.asciidoc

@@ -0,0 +1,27 @@
+[[java-rest-high-main]]
+=== Info API
+
+[[java-rest-high-main-request]]
+==== Execution
+
+Cluster information can be retrieved using the `info()` method:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MainDocumentationIT.java[main-execute]
+--------------------------------------------------
+
+[[java-rest-high-main-response]]
+==== Response
+
+The returned `MainResponse` provides various kinds of information about the cluster:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MainDocumentationIT.java[main-response]
+--------------------------------------------------
+<1> Retrieve the name of the cluster as a `ClusterName`
+<2> Retrieve the unique identifier of the cluster
+<3> Retrieve the name of the node the request has been executed on
+<4> Retrieve the version of the node the request has been executed on
+<5> Retrieve the build information of the node the request has been executed on

docs/java-rest/high-level/index.asciidoc

@@ -22,10 +22,16 @@ the same response objects.
 
 --
 
+:doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation
+
 include::usage.asciidoc[]
 
 include::apis.asciidoc[]
 
 include::apis/index.asciidoc[]
 
+include::migration.asciidoc[]
+
 include::../license.asciidoc[]
+
+:doc-tests!: