From d7c41764f2072a4d9ec3cbbdc3b0d5a2b57ed30b Mon Sep 17 00:00:00 2001 From: javanna Date: Fri, 6 May 2016 11:04:26 +0200 Subject: [PATCH] add some javadocs to connection pool classes --- .../client/AbstractStaticConnectionPool.java | 20 +++++++++++++------ .../client/StaticConnectionPool.java | 3 +++ .../elasticsearch/client/sniff/Sniffer.java | 4 ++-- .../client/sniff/SniffingConnectionPool.java | 4 ++++ 4 files changed, 23 insertions(+), 8 deletions(-) diff --git a/client/src/main/java/org/elasticsearch/client/AbstractStaticConnectionPool.java b/client/src/main/java/org/elasticsearch/client/AbstractStaticConnectionPool.java index 192c1b0f35a..3fe4ead4bbe 100644 --- a/client/src/main/java/org/elasticsearch/client/AbstractStaticConnectionPool.java +++ b/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 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 createConnections(HttpHost... hosts) { List connections = new ArrayList<>(); for (HttpHost host : hosts) { diff --git a/client/src/main/java/org/elasticsearch/client/StaticConnectionPool.java b/client/src/main/java/org/elasticsearch/client/StaticConnectionPool.java index 3e25818fb39..5d54e583abe 100644 --- a/client/src/main/java/org/elasticsearch/client/StaticConnectionPool.java +++ b/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); diff --git a/client/src/main/java/org/elasticsearch/client/sniff/Sniffer.java b/client/src/main/java/org/elasticsearch/client/sniff/Sniffer.java index a812804cbce..ebed97e4a4e 100644 --- a/client/src/main/java/org/elasticsearch/client/sniff/Sniffer.java +++ b/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); diff --git a/client/src/main/java/org/elasticsearch/client/sniff/SniffingConnectionPool.java b/client/src/main/java/org/elasticsearch/client/sniff/SniffingConnectionPool.java index 399bfd8e39b..3fb7885fd14 100644 --- a/client/src/main/java/org/elasticsearch/client/sniff/SniffingConnectionPool.java +++ b/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);