Make ApiClient and subclasses Closeable (#851)

Author: swallez

docs/api-conventions/object-lifecycles.asciidoc

@@ -17,7 +17,7 @@ closed to release the underlying resources such as network connections.
 **Clients**::
 Immutable, stateless and thread-safe.
 These are very lightweight objects that just wrap a transport and provide API
-endpoints as methods.
+endpoints as methods. Closing a client closes the underlying transport.
 
 **Builders**::
 Mutable, non thread-safe.

docs/release-notes/release-highlights.asciidoc

@@ -5,6 +5,10 @@ These are the important new features and changes in minor releases. Every releas
 
 For a list of detailed changes, including bug fixes, please see the https://github.com/elastic/elasticsearch-java/releases[GitHub project realease notes].
 
+[discrete]
+==== Version 8.16
+* `ElasticsearchClient` is now `Closeable`. Closing a client object also closes the underlying transport - https://github.com/elastic/elasticsearch-java/pull/851[#851]
+
 [discrete]
 ==== Version 8.13
 

java-client/src/main/java/co/elastic/clients/ApiClient.java

@@ -26,10 +26,12 @@
 import co.elastic.clients.json.JsonpMapperBase;
 
 import javax.annotation.Nullable;
+import java.io.Closeable;
+import java.io.IOException;
 import java.lang.reflect.Type;
 import java.util.function.Function;
 
-public abstract class ApiClient<T extends Transport, Self extends ApiClient<T, Self>> {
+public abstract class ApiClient<T extends Transport, Self extends ApiClient<T, Self>> implements Closeable {
 
     protected final T transport;
     protected final TransportOptions transportOptions;
@@ -85,4 +87,15 @@ public TransportOptions _transportOptions() {
     public JsonpMapper _jsonpMapper() {
         return transport.jsonpMapper();
     }
+
+    /**
+     * Close this client and associated resources, including the underlying {@link Transport} object.
+     * <p>
+     * If the underlying {@code Transport} object is shared with other API client objects, these objects will also become
+     * unavailable.
+     */
+    @Override
+    public void close() throws IOException {
+        transport.close();
+    }
 }

java-client/src/main/java/co/elastic/clients/elasticsearch/_helpers/bulk/BulkIngester.java

@@ -378,6 +378,10 @@ public void add(Function<BulkOperation.Builder, ObjectBuilder<BulkOperation>> f,
         add(f.apply(new BulkOperation.Builder()).build(), context);
     }
 
+    /**
+     * Close this ingester, first flushing any buffered operations. This <strong>does not close</strong>
+     * the underlying @{link {@link ElasticsearchClient} and {@link co.elastic.clients.transport.Transport}.
+     */
     @Override
     public void close() {
         if (isClosed) {

java-client/src/test/java/co/elastic/clients/documentation/getting_started/ConnectingTest.java

@@ -70,8 +70,8 @@ public void createClient() throws Exception {
 
         // Use the client...
 
-        // Close the transport, freeing the underlying thread
-        transport.close();
+        // Close the client, also closing the underlying transport object and network connections.
+        esClient.close();
         //end::create-client
 
         //tag::first-request
@@ -123,8 +123,8 @@ restClient, new JacksonJsonpMapper(), null, esOtelInstrumentation
 
         // Use the client...
 
-        // Close the transport, freeing the underlying thread
-        transport.close();
+        // Close the client, also closing the underlying transport object and network connections.
+        esClient.close();
         //end::create-client-otel
     }
 
@@ -159,12 +159,12 @@ AuthScope.ANY, new UsernamePasswordCredentials(login, password)
 
         // Create the transport and the API client
         ElasticsearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
-        ElasticsearchClient client = new ElasticsearchClient(transport);
+        ElasticsearchClient esClient = new ElasticsearchClient(transport);
 
         // Use the client...
 
-        // Close the transport, freeing the underlying thread
-        transport.close();
+        // Close the client, also closing the underlying transport object and network connections.
+        esClient.close();
         //end::create-secure-client-cert
     }
 
@@ -199,12 +199,12 @@ AuthScope.ANY, new UsernamePasswordCredentials(login, password)
 
         // Create the transport and the API client
         ElasticsearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
-        ElasticsearchClient client = new ElasticsearchClient(transport);
+        ElasticsearchClient esClient = new ElasticsearchClient(transport);
 
         // Use the client...
 
-        // Close the transport, freeing the underlying thread
-        transport.close();
+        // Close the client, also closing the underlying transport object and network connections.
+        esClient.close();
         //end::create-secure-client-fingerprint
     }