Hrlc compat doc (#228)

docs/migrate.asciidoc

@@ -10,6 +10,31 @@ Migrating from the HLRC therefore requires some code rewrite in your
 application. This transition can however happen progressively as the two client 
 libraries can coexist in a single application with no operational overhead.
 
+[discrete]
+=== Compatibility mode: using a 7.17 client with {es} 8.x
+The HLRC version `7.17` can be used with {es} version `8.x` by enabling
+HLRC's compatibility mode (see code sample below). In this mode HLRC sends
+additional headers that instruct {es} `8.x` to behave like a `7.x` server.
+
+The {java-client} doesn't need this setting as compatibility mode is always
+enabled.
+
+[discrete]
+=== Using the same http client with the HLRC and the Java API Client
+
+To avoid any operational overhead during the transition phase where an
+application would use both the HLRC and the new Java API Client, both clients
+can share the same Low Level Rest Client, which is the network layer that
+manages all connections, round-robin strategies, node sniffing, and so on.
+
+The code below shows how to initialize both clients with the same HTTP client:
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MigrateHlrcTest.java[migrate]
+--------------------------------------------------
+<1> Enables compatibility mode that allows HLRC `7.17` to work with {es} `8.x`.
+
 [discrete]
 === Transition strategies
 
@@ -26,18 +51,3 @@ For example:
   leveraging the tight integration of the new Java API Client with JSON object 
   mappers.
 
-
-[discrete]
-=== Using the same transport with the HLRC and the Java API Client
-
-To avoid any operational overhead during the transition phase where an 
-application would use both the HLRC and the new Java API Client, both clients 
-can share the same Low Level Rest Client, which is the network layer that 
-manages all connections, round-robin strategies, node sniffing, and so on.
-
-The code below shows how to initialize both clients with the same HTTP client:
-
-["source","java"]
---------------------------------------------------
-include-tagged::{doc-tests}/MigrateHlrcTest.java[migrate]
---------------------------------------------------

java-client/src/test/java/co/elastic/clients/documentation/MigrateHlrcTest.java

@@ -25,35 +25,44 @@
 import co.elastic.clients.transport.rest_client.RestClientTransport;
 import org.apache.http.HttpHost;
 import org.elasticsearch.client.RestClient;
-import org.elasticsearch.client.RestClientBuilder;
 import org.junit.Test;
 
 public class MigrateHlrcTest {
 
     // Fake HLRC -- we don't want to import it for just one example
     public static class RestHighLevelClient {
-        public RestHighLevelClient(RestClientBuilder builder) {
+    }
+
+    public static class RestHighLevelClientBuilder {
+
+        public RestHighLevelClientBuilder(RestClient restClient) {
         }
 
-        public RestClient getLowLevelClient() {
-            return null;
+        public RestHighLevelClientBuilder setApiCompatibilityMode(Boolean enabled) {
+            return this;
+        }
+
+        public RestHighLevelClient build() {
+            return new RestHighLevelClient();
         }
     }
 
     @Test
     public void migrate() {
         //tag::migrate
         // Create the low-level client
-        RestClientBuilder httpClientBuilder = RestClient.builder(
+        RestClient httpClient = RestClient.builder(
             new HttpHost("localhost", 9200)
-        );
+        ).build();
 
         // Create the HLRC
-        RestHighLevelClient hlrc = new RestHighLevelClient(httpClientBuilder);
+        RestHighLevelClient hlrc = new RestHighLevelClientBuilder(httpClient)
+            .setApiCompatibilityMode(true) // <1>
+            .build();
 
-        // Create the new Java Client with the same low level client
+        // Create the Java API Client with the same low level client
         ElasticsearchTransport transport = new RestClientTransport(
-            hlrc.getLowLevelClient(),
+            httpClient,
             new JacksonJsonpMapper()
         );