add some javadocs to connection pool classes

client/src/main/java/org/elasticsearch/client/AbstractStaticConnectionPool.java

@@ -29,19 +29,17 @@ import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
 import java.util.concurrent.atomic.AtomicInteger;
-import java.util.function.Predicate;
 import java.util.stream.Stream;
 
 /**
- * Base static connection pool implementation that deals with mutable connections. Marks connections as dead/alive when needed.
- * Provides a stream of alive connections or dead ones that should be retried for each {@link #nextConnection()} call, which
- * allows to filter connections through a customizable {@link Predicate}, called connection selector.
+ * Base static connection pool implementation that marks connections as dead/alive when needed.
+ * Provides a stream of alive connections or dead ones that should be retried for each {@link #nextConnection()} call.
  * In case the returned stream is empty a last resort dead connection should be retrieved by calling {@link #lastResortConnection()}
- * and resurrected so that a single request attempt can be performed.
+ * and resurrected so that a last resort request attempt can be performed.
  * The {@link #onSuccess(Connection)} method marks the connection provided as an argument alive.
  * The {@link #onFailure(Connection)} method marks the connection provided as an argument dead.
  * This base implementation doesn't define the list implementation that stores connections, so that concurrency can be
- * handled in the subclasses depending on the usecase (e.g. defining the list volatile when needed).
+ * handled in subclasses depending on the usecase (e.g. defining the list volatile or final when needed).
  */
 public abstract class AbstractStaticConnectionPool implements ConnectionPool {
 
@@ -49,6 +47,12 @@ public abstract class AbstractStaticConnectionPool implements ConnectionPool {
 
     private final AtomicInteger lastConnectionIndex = new AtomicInteger(0);
 
+    /**
+     * Allows to retrieve the concrete list of connections. Not defined directly as a member
+     * of this class as subclasses may need to handle concurrency if the list can change, for
+     * instance defining the field as volatile. On the other hand static implementations
+     * can just make the list final instead.
+     */
     protected abstract List<Connection> getConnections();
 
     @Override
@@ -64,6 +68,10 @@ public abstract class AbstractStaticConnectionPool implements ConnectionPool {
         return sortedConnections.stream().filter(connection -> connection.isAlive() || connection.shouldBeRetried());
     }
 
+    /**
+     * Helper method to be used by subclasses when needing to create a new list
+     * of connections given their corresponding hosts
+     */
     protected List<Connection> createConnections(HttpHost... hosts) {
         List<Connection> connections = new ArrayList<>();
         for (HttpHost host : hosts) {

client/src/main/java/org/elasticsearch/client/StaticConnectionPool.java

@@ -33,6 +33,9 @@ import java.io.IOException;
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * Static implementation of {@link ConnectionPool}. Its underlying list of connections is immutable.
+ */
 public class StaticConnectionPool extends AbstractStaticConnectionPool {
 
     private static final Log logger = LogFactory.getLog(StaticConnectionPool.class);

client/src/main/java/org/elasticsearch/client/sniff/Sniffer.java

@@ -43,9 +43,9 @@ import java.util.List;
 import java.util.Objects;
 
 /**
- * Calls nodes info api and returns a list of http hosts extracted from it
+ * Calls nodes info api and returns a list of http hosts extracted from it.
  */
-//TODO this could potentially a call to _cat/nodes (although it doesn't support timeout param), but how would we handle bw comp with 2.x?
+//TODO This could potentially be using _cat/nodes which wouldn't require jackson as a dependency, but we'd have bw comp problems with 2.x
 final class Sniffer {
 
     private static final Log logger = LogFactory.getLog(Sniffer.class);

client/src/main/java/org/elasticsearch/client/sniff/SniffingConnectionPool.java

@@ -39,6 +39,10 @@ import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.function.Predicate;
 import java.util.stream.Stream;
 
+/**
+ * Connection pool implementation that sniffs nodes from elasticsearch at regular intervals.
+ * Can optionally sniff nodes on each failure as well.
+ */
 public class SniffingConnectionPool extends AbstractStaticConnectionPool {
 
     private static final Log logger = LogFactory.getLog(SniffingConnectionPool.class);