[Docs] Add migration notes for the high-level rest client (#25911)

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.GetRequest;
 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.action.update.UpdateResponse;
 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,5 +1,3 @@
-:doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation
-
 include::_index.asciidoc[]
 include::get.asciidoc[]
 include::delete.asciidoc[]
@@ -7,5 +5,4 @@ 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!:

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

@@ -0,0 +1,362 @@
+[[java-rest-high-level-migration]]
+== Migration Guide
+
+This section describes how to migrate existing code from the `TransportClient`
+to the new Java High Level REST Client released with the version 5.6.0
+of Elasticsearch.
+
+=== Motivations around a new Java client
+
+The existing `TransportClient` has been part of Elasticsearch since https://github.com/elastic/elasticsearch/blob/b3337c312765e51cec7bde5883bbc0a08f56fb65/modules/elasticsearch/src/main/java/org/elasticsearch/client/transport/TransportClient.java[its very first commit].
+ It is a special client as it uses the transport protocol to communicate with Elasticsearch,
+ which causes compatibility problems if the client is not on the same version as the
+ Elasticsearch instances it talks to.
+
+We released a low-level REST client in 2016, which is based on the well known Apache HTTP
+client and it allows to communicate with an Elasticsearch cluster in any version using HTTP.
+On top of that we released the high-level REST client which is based on the low-level client
+but takes care of request marshalling and response un-marshalling.
+
+If you're interested in knowing more about these changes, we wrote a blog post about the
+https://www.elastic.co/blog/state-of-the-official-elasticsearch-java-clients[state of the official Elasticsearch Java clients].
+
+=== Prerequisite
+
+The Java High Level Rest Client requires Java `1.8` and can be used to send requests
+to an <<java-rest-high-compatibility,Elasticsearch cluster in a compatible version>>.
+
+=== How to migrate
+
+Adapting existing code to use the `RestHighLevelClient` instead of the `TransportClient`
+requires the following steps:
+
+- Update dependencies
+- Update client initialization
+- Update application code
+
+=== Updating the dependencies
+
+Java application that uses the `TransportClient` depends on the
+`org.elasticsearch.client:transport` artifact. This dependency
+must be replaced by a new dependency on the high-level client.
+
+The <<java-rest-high-usage,Getting Started>> page shows
+ typical configurations for Maven and Gradle and presents the
+ <<java-rest-high-usage-dependencies, dependencies>> brought by the
+ high-level client.
+
+=== Changing the client's initialization code
+
+The `TransportClient` is typically initialized as follows:
+[source,java]
+--------------------------------------------------
+Settings settings = Settings.builder()
+        .put("cluster.name", "prod").build();
+
+TransportClient transportClient = new PreBuiltTransportClient(settings)
+        .addTransportAddress(new TransportAddress(InetAddress.getByName("host"), 9300));
+--------------------------------------------------
+
+The initialization of a `RestHighLevelClient` is different. It first requires the initialization
+of a <<java-rest-low-usage-initialization,low-level client>>:
+
+[source,java]
+--------------------------------------------------
+RestClient lowLevelRestClient = RestClient.builder(
+                new HttpHost("host", 9200, "http")).build();
+--------------------------------------------------
+
+NOTE: The `RestClient` uses Elasticsearch's HTTP service which is
+ bounded by default on `9200`. This port is different from the port
+ used to connect to Elasticsearch with a `TransportClient`.
+
+Which is then passed to the constructor of the `RestHighLevelClient`:
+
+[source,java]
+--------------------------------------------------
+RestHighLevelClient client =
+    new RestHighLevelClient(lowLevelRestClient);
+--------------------------------------------------
+
+Both `RestClient` and `RestHighLevelClient` are thread safe. They are
+ typically instantiated by the application at startup time or when the
+ first request is executed.
+
+Once the `RestHighLevelClient` is initialized, it can then be used to
+execute any of the <<java-rest-high-supported-apis,supported APIs>>.
+
+As with the `TransportClient`, the `RestClient` must be closed when it
+is not needed anymore or when the application is stopped.
+
+So the code that closes the `TransportClient`:
+
+[source,java]
+--------------------------------------------------
+transportClient.close();
+--------------------------------------------------
+
+Must be replaced with:
+
+[source,java]
+--------------------------------------------------
+lowLevelRestClient.close();
+--------------------------------------------------
+
+=== Changing the application's code
+
+The `RestHighLevelClient` supports the same request and response objects
+as the `TransportClient`, but exposes slightly different methods to
+send the requests.
+
+More importantly, the high-level client:
+
+- does not support request builders. The legacy methods like
+`client.prepareIndex()` must be changed to use
+ request constructors like `new IndexRequest()` to create requests
+ objects. The requests are then executed using synchronous or
+ asynchronous dedicated methods like `client.index()` or `client.indexAsync()`.
+- does not provide indices or cluster management APIs. Management
+operations can be executed by external scripts or
+<<java-rest-high-level-migration-manage-indices, using the low-level client>>.
+
+==== How to migrate the way requests are built
+
+The Java API provides two ways to build a request: by using the request's constructor or by using
+a request builder. Migrating from the `TransportClient` to the high-level client can be
+straightforward if application's code uses the former, while changing usages of the latter can
+require more work.
+
+[[java-rest-high-level-migration-request-ctor]]
+===== With request constructors
+
+When request constructors are used, like in the following example:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-request-ctor]
+--------------------------------------------------
+<1> Create an `IndexRequest` using its constructor
+
+The migration is very simple. The execution using the `TransportClient`:
+
+[source,java]
+--------------------------------------------------
+IndexResponse response = transportClient.index(indexRequest).actionGet();
+--------------------------------------------------
+
+Can be easily replaced to use the `RestHighLevelClient`:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-request-ctor-execution]
+--------------------------------------------------
+
+[[java-rest-high-level-migration-request-builder]]
+===== With request builders
+
+The Java API provides a request builder for every type of request. They are exposed by the
+`TransportClient` through the many `prepare()` methods. Here are some examples:
+
+[source,java]
+--------------------------------------------------
+IndexRequestBuilder indexRequestBuilder   = transportClient.prepareIndex();  // <1>
+DeleteRequestBuilder deleteRequestBuilder = transportClient.prepareDelete(); // <2>
+SearchRequestBuilder searchRequestBuilder = transportClient.prepareSearch(); // <3>
+--------------------------------------------------
+<1> Create a `IndexRequestBuilder` using the `prepareIndex()` method from the `TransportClient`. The
+request builder encapsulates the `IndexRequest` to be executed.
+<2> Create a `DeleteRequestBuilder` using the `prepareDelete()` method from the `TransportClient`. The
+request builder encapsulates the `DeleteRequest` to be executed.
+<3> Create a `SearchRequestBuilder` using the `prepareSearch()` method from the `TransportClient`. The
+request builder encapsulates the `SearchRequest` to be executed.
+
+Since the Java High Level REST Client does not support request builders, applications that use
+them must be changed to use <<java-rest-high-level-migration-request-ctor,requests constructors>> instead.
+
+NOTE: While you are incrementally migrating your application and you have both the transport client
+and the high level client available you can always get the `Request` object from the `Builder` object
+by calling `Builder.request()`. We do not advise continuing to depend on the builders in the long run
+but it should be possible to use them during the transition from the transport client to the high
+level rest client.
+
+==== How to migrate the way requests are executed
+
+The `TransportClient` allows to execute requests in both synchronous and asynchronous ways. This is also
+possible using the high-level client.
+
+===== Synchronous execution
+
+The following example shows how a `DeleteRequest` can be synchronously executed using the `TransportClient`:
+
+[source,java]
+--------------------------------------------------
+DeleteRequest request = new DeleteRequest("index", "doc", "id"); // <1>
+DeleteResponse response = transportClient.delete(request).actionGet(); // <2>
+--------------------------------------------------
+<1> Create the `DeleteRequest` using its constructor
+<2> Execute the `DeleteRequest`. The `actionGet()` method blocks until a
+response is returned by the cluster.
+
+The same request synchronously executed using the high-level client is:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-request-sync-execution]
+--------------------------------------------------
+<1> Execute the `DeleteRequest`. The `delete()` method blocks until a
+response is returned by the cluster.
+
+===== Asynchronous execution
+
+The following example shows how a `DeleteRequest` can be asynchronously executed using the `TransportClient`:
+
+[source,java]
+--------------------------------------------------
+DeleteRequest request = new DeleteRequest("index", "doc", "id"); // <1>
+transportClient.delete(request, new ActionListener<DeleteResponse>() { // <2>
+    @Override
+    public void onResponse(DeleteResponse deleteResponse) {
+        // <3>
+    }
+
+    @Override
+    public void onFailure(Exception e) {
+        // <4>
+    }
+});
+--------------------------------------------------
+<1> Create the `DeleteRequest` using its constructor
+<2> Execute the `DeleteRequest` by passing the request and a
+`ActionListener` that gets called on execution completion or
+failure. This method does not block and returns immediately.
+<3> The `onResponse()` method is called when the response is
+returned by the cluster.
+<4> The `onFailure()` method is called when an error occurs
+during the execution of the request.
+
+The same request asynchronously executed using the high-level client is:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-request-async-execution]
+--------------------------------------------------
+<1> Create the `DeleteRequest` using its constructor
+<2> Execute the `DeleteRequest` by passing the request and a
+`ActionListener` that gets called on execution completion or
+failure. This method does not block and returns immediately.
+<3> The `onResponse()` method is called when the response is
+returned by the cluster.
+<4> The `onFailure()` method is called when an error occurs
+during the execution of the request.
+
+[[java-rest-high-level-migration-manage-indices]]
+==== Manage Indices using the Low-Level REST Client
+
+The low-level client is able to execute any kind of HTTP requests, and can
+therefore be used to call the APIs that are not yet supported by the high level client.
+
+For example, creating a new index with the `TransportClient` may look like this:
+
+[source,java]
+--------------------------------------------------
+Settings settings = Settings.builder() // <1>
+                                .put(SETTING_NUMBER_OF_SHARDS, 1)
+                                .put(SETTING_NUMBER_OF_REPLICAS, 0)
+                                .build();
+
+String mappings = XContentFactory.jsonBuilder()  // <2>
+                                .startObject()
+                                    .startObject("doc")
+                                        .startObject("properties")
+                                            .startObject("time")
+                                                .field("type", "date")
+                                            .endObject()
+                                        .endObject()
+                                    .endObject()
+                                .endObject()
+                                .string();
+
+CreateIndexResponse response = transportClient.admin().indices()  // <3>
+        .prepareCreate("my-index")
+        .setSettings(indexSettings)
+        .addMapping("doc", docMapping, XContentType.JSON)
+        .get();
+
+if (response.isAcknowledged() == false) {
+    // <4>
+}
+--------------------------------------------------
+<1> Define the settings of the index
+<2> Define the mapping for document of type `doc` using a
+`XContentBuilder`
+<3> Create the index with the previous settings and mapping
+using the `prepareCreate()` method. The execution is synchronous
+and blocks on the `get()` method until the remote cluster returns
+a response.
+<4> Handle the situation where the index has not been created
+
+The same operation executed with the low-level client could be:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-create-inded]
+--------------------------------------------------
+<1> Define the settings of the index
+<2> Define the body of the HTTP request using a `XContentBuilder` with JSON format
+<3> Include the settings in the request body
+<4> Include the mappings in the request body
+<5> Convert the request body from `String` to a `HttpEntity` and
+set its content type (here, JSON)
+<6> Execute the request using the low-level client. The execution is synchronous
+and blocks on the `performRequest()` method until the remote cluster returns
+a response.
+<7> Handle the situation where the index has not been created
+
+
+[[java-rest-high-level-migration-cluster-health]]
+==== Checking Cluster Health using the Low-Level REST Client
+
+Another common need is to check the cluster's health using the Cluster API. With
+the `TransportClient` it can be done this way:
+
+[source,java]
+--------------------------------------------------
+ClusterHealthResponse response = client.admin().cluster().prepareHealth().get(); // <1>
+
+ClusterHealthStatus healthStatus = response.getStatus(); // <2>
+if (healthStatus != ClusterHealthStatus.GREEN) {
+    // <3>
+}
+--------------------------------------------------
+<1> Execute a `ClusterHealth` with default parameters
+<2> Retrieve the cluster's health status from the response
+<3> Handle the situation where the cluster's health is not green
+
+With the low-level client, the code can be changed to:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrationDocumentationIT.java[migration-cluster-health]
+--------------------------------------------------
+<1> Call the cluster's health REST endpoint using the default paramaters
+and gets back a `Response` object
+<2> Retrieve an `InputStream` object in order to read the response's content
+<3> Parse the response's content using Elasticsearch's helper class `XContentHelper`. This
+ helper requires the content type of the response to be passed as an argument and returns
+ a `Map` of objects. Values in the map can be of any type, including inner `Map` that are
+ used to represent the JSON object hierarchy.
+<4> Retrieve the value of the `status` field in the response map, casts it as a a `String`
+object and use the `ClusterHealthStatus.fromString()` method to convert it as a `ClusterHealthStatus`
+object. This method throws an exception if the value does not corresponds to a valid cluster
+health status.
+<5> Handle the situation where the cluster's health is not green
+
+Note that for convenience this example uses Elasticsearch's helpers to parse the JSON response
+body, but any other JSON parser could have been use instead.
+
+=== Provide feedback
+
+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].
+
+

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

@@ -4,6 +4,21 @@
 This section describes how to get started with the high-level REST client from
 getting the artifact to using it in an application.
 
+[[java-rest-high-compatibility]]
+=== Compatibility
+The Java High Level REST Client requires Java 1.8 and depends on the Elasticsearch
+core project. The client version is the same as the Elasticsearch version that the
+client was developed for. It accepts the same request arguments as the `TransportClient`
+and returns the same response objects.
+
+The High Level Client is backwards compatible but can only communicate with Elasticsearch
+version 5.5 and onwards. The High Level Client is forward compatible as well, meaning that
+it supports communicating with a later version of Elasticsearch than the one it was developed
+for. It is recommended to upgrade the High Level Client when upgrading the Elasticsearch
+cluster to a new major version, as REST API breaking changes may cause unexpected results,
+and newly added APIs will only be supported by the newer version of the client. The client
+should be updated last, once all of the nodes in the cluster have been upgraded.
+
 [[java-rest-high-javadoc]]
 === Javadoc
 

docs/reference/migration/migrate_6_0.asciidoc

@@ -26,6 +26,7 @@ way to reindex old indices is to use the `reindex` API.
 
 * <<breaking_60_aggregations_changes>>
 * <<breaking_60_cat_changes>>
+* <<breaking_60_clients_changes>>
 * <<breaking_60_cluster_changes>>
 * <<breaking_60_docs_changes>>
 * <<breaking_60_indices_changes>>
@@ -46,6 +47,7 @@ way to reindex old indices is to use the `reindex` API.
 include::migrate_6_0/aggregations.asciidoc[]
 include::migrate_6_0/analysis.asciidoc[]
 include::migrate_6_0/cat.asciidoc[]
+include::migrate_6_0/clients.asciidoc[]
 include::migrate_6_0/cluster.asciidoc[]
 include::migrate_6_0/docs.asciidoc[]
 include::migrate_6_0/indices.asciidoc[]

docs/reference/migration/migrate_6_0/clients.asciidoc

@@ -0,0 +1,11 @@
+[[breaking_60_clients_changes]]
+=== Clients changes
+
+==== Java High Level REST Client
+
+Starting from version 5.6.0 a new Java client has been released: the Java High Level REST Client.
+This official high-level client (named like this to differentiate it from the existing low-level client) for
+Elasticsearch can be used to execute search, index, delete, update and bulk operations using the same Core
+Java classes as the `TransportClient` uses.
+
+This Java High Level REST Client is designed to replace the `TransportClient` in a near future.