Add rest5_client docs

Author: swallez

docs/reference/_snippets/legacy-rest-client.md

@@ -0,0 +1,3 @@
+:::{note}
+This is the legacy RestClient. Please migrate to [Rest5Client](/reference/transport/rest5-client/index.md), a drop-in replacement with an up-to-date http library.
+:::

docs/reference/api-conventions/blocking-async.md

@@ -12,9 +12,9 @@ Both flavors can be used at the same time depending on your needs, sharing the s
 % :::{include-code} src={{doc-tests-src}}/api_conventions/ApiConventionsTest.java tag=blocking-and-async
 ```java
 // Synchronous blocking client
-ElasticsearchClient client = new ElasticsearchClient(transport);
+ElasticsearchClient esClient = new ElasticsearchClient(transport);
 
-if (client.exists(b -> b.index("products").id("foo")).value()) {
+if (esClient.exists(b -> b.index("products").id("foo")).value()) {
     logger.info("product exists");
 }
 

docs/reference/api-conventions/building-objects.md

@@ -12,8 +12,8 @@ All data types in the Java API Client are immutable. Object creation uses the [b
 
 % :::{include-code} src={{doc-tests-src}}/api_conventions/ApiConventionsTest.java tag=builders
 ```java
-ElasticsearchClient client = createClient();
-CreateIndexResponse createResponse = client.indices().create(
+ElasticsearchClient esClient = createClient();
+CreateIndexResponse createResponse = esClient.indices().create(
     new CreateIndexRequest.Builder()
         .index("my-index")
         .aliases("foo",
@@ -32,8 +32,8 @@ Although this works nicely, having to instantiate builder classes and call the `
 
 % :::{include-code} src={{doc-tests-src}}/api_conventions/ApiConventionsTest.java tag=builder-lambdas
 ```java
-ElasticsearchClient client = createClient();
-CreateIndexResponse createResponse = client.indices()
+ElasticsearchClient esClient = createClient();
+CreateIndexResponse createResponse = esClient.indices()
     .create(createIndexBuilder -> createIndexBuilder
         .index("my-index")
         .aliases("foo", aliasBuilder -> aliasBuilder
@@ -48,8 +48,8 @@ Note in the above example that builder variables are only used to start a chain
 
 % :::{include-code} src={{doc-tests-src}}/api_conventions/ApiConventionsTest.java tag=builder-lambdas-short
 ```java
-ElasticsearchClient client = createClient();
-CreateIndexResponse createResponse = client.indices()
+ElasticsearchClient esClient = createClient();
+CreateIndexResponse createResponse = esClient.indices()
     .create(c -> c
         .index("my-index")
         .aliases("foo", a -> a
@@ -64,8 +64,8 @@ This example also highlights a useful naming convention for builder parameters i
 
 % :::{include-code} src={{doc-tests-src}}/api_conventions/ApiConventionsTest.java tag=builder-intervals
 ```java
-ElasticsearchClient client = createClient();
-SearchResponse<SomeApplicationData> results = client
+ElasticsearchClient esClient = createClient();
+SearchResponse<SomeApplicationData> results = esClient
     .search(b0 -> b0
         .query(b1 -> b1
             .intervals(b2 -> b2

docs/reference/api-conventions/loading-json.md

@@ -41,7 +41,7 @@ CreateIndexRequest req = CreateIndexRequest.of(b -> b
     .withJson(input) // <2>
 );
 
-boolean created = client.indices().create(req).acknowledged();
+boolean created = esClient.indices().create(req).acknowledged();
 ```
 
 1. open an input stream for the JSON resource file.
@@ -64,7 +64,7 @@ req = IndexRequest.of(b -> b
     .withJson(file)
 );
 
-client.index(req);
+esClient.index(req);
 ```
 
 1. when calling `withJson()` on data structures that have generic type parameters, these generic types will be considered to be `JsonData`.
@@ -102,7 +102,7 @@ SearchRequest aggRequest = SearchRequest.of(b -> b
     .size(0)
 );
 
-Map<String, Aggregate> aggs = client
+Map<String, Aggregate> aggs = esClient
     .search(aggRequest, Void.class) // <3>
     .aggregations();
 ```
@@ -157,7 +157,7 @@ SearchRequest aggRequest = SearchRequest.of(b -> b
     .ignoreUnavailable(true) // <5>
 );
 
-Map<String, Aggregate> aggs = client
+Map<String, Aggregate> aggs = esClient
     .search(aggRequest, Void.class)
     .aggregations();
 ```

docs/reference/setup/installation.md

@@ -26,7 +26,7 @@ dependencies {
 
 In the `pom.xml` of your project, add the following repository definition and dependencies:
 
-```xml
+```xml subs=true
 <project>
   <dependencies>
 

docs/reference/toc.yml

@@ -39,6 +39,30 @@ toc:
     children:
       - file: index.md
 
+      - folder: rest5-client
+        children:
+          - file: index.md
+          - folder: usage
+            children:
+              - file: index.md
+              - file: initialization.md
+              - file: requests.md
+              - file: responses.md
+              - file: logging.md
+          - folder: config
+            children:
+              - file: index.md
+              - file: timeouts.md
+              - file: number_of_threads.md
+              - file: basic_authentication.md
+              - file: other_authentication_methods.md
+              - file: encrypted_communication.md
+              - file: others.md
+              - file: node_selector.md
+          - folder: sniffer
+            children:
+              - file: index.md
+
       - folder: rest-client
         children:
           - file: index.md

docs/reference/transport/rest-client/config/basic_authentication.md

@@ -5,6 +5,9 @@ mapped_pages:
 
 # Basic authentication [_basic_authentication]
 
+:::{include} /reference/_snippets/legacy-rest-client.md
+:::
+
 Configuring basic authentication can be done by providing an `HttpClientConfigCallback` while building the `RestClient` through its builder. The interface has one method that receives an instance of [`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`](https://hc.apache.org/httpcomponents-asyncclient-4.1.x/current/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html) as an argument and has the same return type. The http client builder can be modified and then returned. In the following example we set a default credentials provider that requires basic authentication.
 
 ```java

docs/reference/transport/rest-client/config/encrypted_communication.md

@@ -5,6 +5,9 @@ mapped_pages:
 
 # Encrypted communication [_encrypted_communication]
 
+:::{include} /reference/_snippets/legacy-rest-client.md
+:::
+
 Encrypted communication using TLS can also be configured through the `HttpClientConfigCallback`. The [`org.apache.http.impl.nio.client.HttpAsyncClientBuilder`](https://hc.apache.org/httpcomponents-asyncclient-4.1.x/current/httpasyncclient/apidocs/org/apache/http/impl/nio/client/HttpAsyncClientBuilder.html) received as an argument exposes multiple methods to configure encrypted communication: `setSSLContext`, `setSSLSessionStrategy` and `setConnectionManager`, in order of precedence from the least important.
 
 When accessing an Elasticsearch cluster that is setup for TLS on the HTTP layer, the client needs to trust the certificate that Elasticsearch is using. The following is an example of setting up the client to trust the CA that has signed the certificate that Elasticsearch is using, when that CA certificate is available in a PKCS#12 keystore:

docs/reference/transport/rest-client/config/index.md

@@ -5,6 +5,9 @@ mapped_pages:
 
 # Common configuration [java-rest-low-config]
 
+:::{include} /reference/_snippets/legacy-rest-client.md
+:::
+
 As explained in [Initialization](../usage/initialization.md), the `RestClientBuilder` supports providing both a `RequestConfigCallback` and an `HttpClientConfigCallback` which allow for any customization that the Apache Async Http Client exposes. Those callbacks make it possible to modify some specific behaviour of the client without overriding every other default configuration that the `RestClient` is initialized with. This section describes some common scenarios that require additional configuration for the low-level Java REST Client.
 
 

docs/reference/transport/rest-client/config/node_selector.md

@@ -5,6 +5,9 @@ mapped_pages:
 
 # Node selector [_node_selector]
 
+:::{include} /reference/_snippets/legacy-rest-client.md
+:::
+
 The client sends each request to one of the configured nodes in round-robin fashion. Nodes can optionally be filtered through a node selector that needs to be provided when initializing the client. This is useful when sniffing is enabled, in case no dedicated master nodes should be hit by HTTP requests. For each request the client will run the eventually configured node selector to filter the node candidates, then select the next one in the list out of the remaining ones.
 
 ```java