Make ApiClient and subclasses Closeable (#851) (#857)

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.

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

@@ -373,6 +373,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

@@ -46,11 +46,16 @@ public void createClient() throws Exception {
             restClient, new JacksonJsonpMapper());
 
         // And create the API client
-        ElasticsearchClient client = new ElasticsearchClient(transport);
+        ElasticsearchClient esClient = new ElasticsearchClient(transport);
+
+        // Use the client...
+
+        // Close the client, also closing the underlying transport object and network connections.
+        esClient.close();
         //end::create-client
 
         //tag::first-request
-        SearchResponse<Product> search = client.search(s -> s
+        SearchResponse<Product> search = esClient.search(s -> s
             .index("products")
             .query(q -> q
                 .term(t -> t