Deprecate RestClientTransport (opensearch-project#536)

Signed-off-by: Andriy Redko <andriy.redko@aiven.io>
okhasawn · Jun 27, 2023 · 3d76737 · 3d76737
1 parent f606949
commit 3d76737
Show file tree

Hide file tree

Showing 6 changed files with 48 additions and 30 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Migrate client transports to Apache HttpClient / Core 5.x ([#246](https://github.com/opensearch-project/opensearch-java/pull/246))
 
 ### Deprecated
+- Deprecate RestClientTransport ((#536)[https://github.com/opensearch-project/opensearch-java/pull/536])
 
 ### Removed
 

diff --git a/USER_GUIDE.md b/USER_GUIDE.md
@@ -81,35 +81,7 @@ static class IndexData {
 
 ## Create a client
 
-There are multiple low level transports which `OpenSearchClient` could be configured with.
-
-### Create a client using `RestClientTransport`
-
-```java
-import org.apache.hc.core5.http.HttpHost;
-
-final HttpHost[] hosts = new HttpHost[] {
-    new HttpHost("http", "localhost", 9200)
-  };
-
-// Initialize the client with SSL and TLS enabled
-final RestClient restClient = RestClient
-  .builder(hosts)
-  .build();
-
-OpenSearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper()); 
-OpenSearchClient client = new OpenSearchClient(transport);
-```
-
-The `JacksonJsonpMapper` class (2.x versions) only supports Java 7 objects by default. [Java 8 modules](https://github.com/FasterXML/jackson-modules-java8) to support JDK8 classes such as the Date and Time API (JSR-310), `Optional`, and more can be used by including [the additional datatype dependency](https://github.com/FasterXML/jackson-modules-java8#usage) and adding the module.  For example, to include JSR-310 classes:
-
-```java
-OpenSearchTransport transport = new RestClientTransport(restClient,
-    new JacksonJsonpMapper(new ObjectMapper().registerModule(new JavaTimeModule()))); 
-OpenSearchClient client = new OpenSearchClient(transport);
-```
-
-Upcoming OpenSearch `3.0.0` release brings HTTP/2 support and as such, the `RestClientTransport` would switch to HTTP/2 if available (for both HTTPS and/or HTTP protocols). The desired protocol could be forced using `RestClientBuilder.HttpClientConfigCallback`.
+There are multiple low level transports which `OpenSearchClient` could be configured with, the `ApacheHttpClient5Transport` being the default one.
 
 ### Create a client using `ApacheHttpClient5Transport`
 
@@ -143,6 +115,34 @@ final OpenSearchTransport transport = ApacheHttpClient5TransportBuilder
 OpenSearchClient client = new OpenSearchClient(transport);
 ```
 
+### Create a client using `RestClientTransport` (deprecated)
+
+```java
+import org.apache.hc.core5.http.HttpHost;
+
+final HttpHost[] hosts = new HttpHost[] {
+    new HttpHost("http", "localhost", 9200)
+  };
+
+// Initialize the client with SSL and TLS enabled
+final RestClient restClient = RestClient
+  .builder(hosts)
+  .build();
+
+OpenSearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper()); 
+OpenSearchClient client = new OpenSearchClient(transport);
+```
+
+The `JacksonJsonpMapper` class (2.x versions) only supports Java 7 objects by default. [Java 8 modules](https://github.com/FasterXML/jackson-modules-java8) to support JDK8 classes such as the Date and Time API (JSR-310), `Optional`, and more can be used by including [the additional datatype dependency](https://github.com/FasterXML/jackson-modules-java8#usage) and adding the module.  For example, to include JSR-310 classes:
+
+```java
+OpenSearchTransport transport = new RestClientTransport(restClient,
+    new JacksonJsonpMapper(new ObjectMapper().registerModule(new JavaTimeModule()))); 
+OpenSearchClient client = new OpenSearchClient(transport);
+```
+
+Upcoming OpenSearch `3.0.0` release brings HTTP/2 support and as such, the `RestClientTransport` would switch to HTTP/2 if available (for both HTTPS and/or HTTP protocols). The desired protocol could be forced using `RestClientBuilder.HttpClientConfigCallback`.
+
 ## Create an index
 
 ### Create an index with default settings

diff --git a/java-client/build.gradle.kts b/java-client/build.gradle.kts
@@ -148,9 +148,13 @@ dependencies {
     val jacksonDatabindVersion = "2.15.2"
 
     // Apache 2.0
-    implementation("org.opensearch.client", "opensearch-rest-client", opensearchVersion)
+    compileOnly("org.opensearch.client", "opensearch-rest-client", opensearchVersion)
     testImplementation("org.opensearch.test", "framework", opensearchVersion)
 
+    api("org.apache.httpcomponents.client5:httpclient5:5.1.4")
+    api("org.apache.httpcomponents.core5:httpcore5:5.1.5")
+    api("org.apache.httpcomponents.core5:httpcore5-h2:5.1.5")
+
     // Apache 2.0
     // https://search.maven.org/artifact/com.google.code.findbugs/jsr305
     api("com.google.code.findbugs:jsr305:3.0.2")

diff --git a/...src/main/java/org/opensearch/client/transport/httpclient5/ApacheHttpClient5Transport.java b/...src/main/java/org/opensearch/client/transport/httpclient5/ApacheHttpClient5Transport.java
@@ -90,6 +90,9 @@
 import jakarta.json.stream.JsonGenerator;
 import jakarta.json.stream.JsonParser;
 
+/**
+ * Apache HttpClient 5 based client transport.
+ */
 public class ApacheHttpClient5Transport implements OpenSearchTransport {
     private static final Log logger = LogFactory.getLog(ApacheHttpClient5Transport.class);
     static final ContentType JsonContentType = ContentType.APPLICATION_JSON;

diff --git a/java-client/src/main/java/org/opensearch/client/transport/rest_client/RestClientOptions.java b/java-client/src/main/java/org/opensearch/client/transport/rest_client/RestClientOptions.java
@@ -48,6 +48,11 @@
 import static org.opensearch.client.transport.TransportHeaders.ACCEPT;
 import static org.opensearch.client.transport.TransportHeaders.USER_AGENT;
 
+/**
+ * The {@link RestClientTransport} is deprecated and is scheduled for removal in later versions. Please
+ * use {@link org.opensearch.client.transport.httpclient5.ApacheHttpClient5Transport} instead.
+ */
+@Deprecated(since = "3.0.0", forRemoval = true)
 public class RestClientOptions implements TransportOptions {
 
     private final RequestOptions options;

diff --git a/...client/src/main/java/org/opensearch/client/transport/rest_client/RestClientTransport.java b/...client/src/main/java/org/opensearch/client/transport/rest_client/RestClientTransport.java
@@ -70,6 +70,11 @@
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * The {@link RestClientTransport} is deprecated and is scheduled for removal in later versions. Please
+ * use {@link org.opensearch.client.transport.httpclient5.ApacheHttpClient5Transport} instead.
+ */
+@Deprecated(since = "3.0.0", forRemoval = true)
 public class RestClientTransport implements OpenSearchTransport {
 
     static final ContentType JsonContentType = ContentType.APPLICATION_JSON;