From 77670c6f254f9230b430398d921db3569de1efc5 Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Sat, 11 Apr 2026 08:54:49 -0400 Subject: [PATCH 1/3] Add missing Javadoc for ConnectionConfig --- .../client5/http/config/ConnectionConfig.java | 85 ++++++++++++++++++- 1 file changed, 82 insertions(+), 3 deletions(-) diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java index 5c2f654985..922ae84aa7 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java @@ -44,6 +44,16 @@ public class ConnectionConfig implements Cloneable { private static final Timeout DEFAULT_CONNECT_TIMEOUT = Timeout.ofMinutes(3); + /** + * The default connection configuration. + * + */ public static final ConnectionConfig DEFAULT = new Builder().build(); private final Timeout connectTimeout; @@ -74,6 +84,10 @@ protected ConnectionConfig() { } /** + * Gets the default socket timeout value for I/O operations on connections created by this configuration. + * A timeout value of zero is interpreted as an infinite timeout. + * + * @return the default socket timeout value, defaults to null. * @see Builder#setSocketTimeout(Timeout) */ public Timeout getSocketTimeout() { @@ -81,6 +95,12 @@ public Timeout getSocketTimeout() { } /** + * Gets the timeout until a new connection is fully established. + *

+ * A timeout value of zero is interpreted as an infinite timeout. + *

+ * + * @return the timeout until a new connection is fully established, defaults to 3 minutes. * @see Builder#setConnectTimeout(Timeout) */ public Timeout getConnectTimeout() { @@ -88,6 +108,12 @@ public Timeout getConnectTimeout() { } /** + * Gets the maximum period of idleness for a connection. + *

+ * Implementations can use this value to discard connections that have been idle for too long. + *

+ * + * @return the maximum period of idleness for a connection, defaults to null. * @see Builder#setIdleTimeout(Timeout) */ public Timeout getIdleTimeout() { @@ -95,6 +121,9 @@ public Timeout getIdleTimeout() { } /** + * Gets the period of inactivity after which persistent connections must be re-validated. + * + * @return the period of inactivity after which persistent connections must be re-validated, defaults to null. * @see Builder#setValidateAfterInactivity(TimeValue) */ public TimeValue getValidateAfterInactivity() { @@ -102,6 +131,9 @@ public TimeValue getValidateAfterInactivity() { } /** + * Gets the total span of time connections can be kept alive or execute requests. + * + * @return the total span of time connections can be kept alive or execute requests, defaults to null. * @see Builder#setTimeToLive(TimeValue) (TimeValue) */ public TimeValue getTimeToLive() { @@ -126,10 +158,21 @@ public String toString() { return builder.toString(); } + /** + * Creates a new builder for {@link ConnectionConfig}. + * + * @return a new builder for {@link ConnectionConfig}. + */ public static ConnectionConfig.Builder custom() { return new Builder(); } + /** + * Creates a new builder for {@link ConnectionConfig} based on an existing instance. + * + * @param config the instance to copy. + * @return a new builder for {@link ConnectionConfig}. + */ public static ConnectionConfig.Builder copy(final ConnectionConfig config) { return new Builder() .setConnectTimeout(config.getConnectTimeout()) @@ -138,6 +181,9 @@ public static ConnectionConfig.Builder copy(final ConnectionConfig config) { .setTimeToLive(config.getTimeToLive()); } + /** + * Builder for {@link ConnectionConfig}. + */ public static class Builder { private Timeout socketTimeout; @@ -152,6 +198,10 @@ public static class Builder { } /** + * Sets the default socket timeout value for I/O operations on connections created by this configuration. + * + * @param soTimeout The default socket timeout value for I/O operations. + * @param timeUnit The time unit of the soTimeout parameter. * @return this instance. * @see #setSocketTimeout(Timeout) */ @@ -161,7 +211,7 @@ public Builder setSocketTimeout(final int soTimeout, final TimeUnit timeUnit) { } /** - * Determines the default socket timeout value for I/O operations on + * Sets the default socket timeout value for I/O operations on * connections created by this configuration. * A timeout value of zero is interpreted as an infinite timeout. *

@@ -174,6 +224,7 @@ public Builder setSocketTimeout(final int soTimeout, final TimeUnit timeUnit) { * Default: {@code null} (undefined) *

* + * @param soTimeout The default socket timeout value for I/O operations. * @return this instance. */ public Builder setSocketTimeout(final Timeout soTimeout) { @@ -182,7 +233,7 @@ public Builder setSocketTimeout(final Timeout soTimeout) { } /** - * Determines the timeout until a new connection is fully established. + * Sets the timeout until a new connection is fully established. *

* A timeout value of zero is interpreted as an infinite timeout. *

@@ -190,6 +241,7 @@ public Builder setSocketTimeout(final Timeout soTimeout) { * Default: 3 minutes *

* + * @param connectTimeout The timeout until a new connection is fully established. * @return this instance. */ public Builder setConnectTimeout(final Timeout connectTimeout) { @@ -198,6 +250,10 @@ public Builder setConnectTimeout(final Timeout connectTimeout) { } /** + * Sets the timeout until a new connection is fully established. + * + * @param connectTimeout The timeout until a new connection is fully established. + * @param timeUnit The time unit of the timeout parameter. * @return this instance. * @see #setConnectTimeout(Timeout) */ @@ -217,6 +273,7 @@ public Builder setConnectTimeout(final long connectTimeout, final TimeUnit timeU * Default: {@code null} (undefined) *

* + * @param idleTimeout The maximum period of idleness for a connection. * @return this instance. * * @since 5.6 @@ -227,6 +284,13 @@ public Builder setIdleTimeout(final Timeout idleTimeout) { } /** + * Sets the maximum period of idleness for a connection. + *

+ * Connections that are idle for longer than {@code idleTimeout} are no longer eligible for reuse. + *

+ * + * @param idleTimeout The maximum period of idleness for a connection. + * @param timeUnit * @return this instance. * @see #setIdleTimeout(Timeout) */ @@ -236,13 +300,14 @@ public Builder setIdleTimeout(final long idleTimeout, final TimeUnit timeUnit) { } /** - * Defines period of inactivity after which persistent connections must + * Sets the period of inactivity after which persistent connections must * be re-validated prior to being leased to the consumer. Negative values passed * to this method disable connection validation. *

* Default: {@code null} (undefined) *

* + * @param validateAfterInactivity The period of inactivity after which persistent connections must be re-validated. * @return this instance. */ public Builder setValidateAfterInactivity(final TimeValue validateAfterInactivity) { @@ -251,6 +316,10 @@ public Builder setValidateAfterInactivity(final TimeValue validateAfterInactivit } /** + * Sets the period of inactivity after which persistent connections must be re-validated prior to being leased to the consumer. + * + * @param validateAfterInactivity The period of inactivity after which persistent connections must be re-validated. + * @param timeUnit The time unit of the validateAfterInactivity parameter. * @return this instance. * @see #setValidateAfterInactivity(TimeValue) */ @@ -265,6 +334,7 @@ public Builder setValidateAfterInactivity(final long validateAfterInactivity, fi * Default: {@code null} (undefined) *

* + * @param timeToLive The total span of time connections can be kept alive or execute requests. * @return this instance. */ public Builder setTimeToLive(final TimeValue timeToLive) { @@ -273,6 +343,10 @@ public Builder setTimeToLive(final TimeValue timeToLive) { } /** + * Sets the total span of time connections can be kept alive or execute requests. + * + * @param timeToLive The total span of time connections can be kept alive or execute requests. + * @param timeUnit The time unit of the timeToLive parameter. * @return this instance. * @see #setTimeToLive(TimeValue) */ @@ -281,6 +355,11 @@ public Builder setTimeToLive(final long timeToLive, final TimeUnit timeUnit) { return this; } + /** + * Builds a new {@link ConnectionConfig} instance based on the values provided to the setters methods. + * + * @return a new {@link ConnectionConfig} instance. + */ public ConnectionConfig build() { return new ConnectionConfig( connectTimeout != null ? connectTimeout : DEFAULT_CONNECT_TIMEOUT, From dbb960a5565ebb1c0bc4d788ad24f26b7b59fa91 Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Sat, 11 Apr 2026 15:34:55 -0400 Subject: [PATCH 2/3] Adjust text after PR review. --- .../apache/hc/client5/http/config/ConnectionConfig.java | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java index 922ae84aa7..527dfee84b 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java @@ -95,12 +95,16 @@ public Timeout getSocketTimeout() { } /** - * Gets the timeout until a new connection is fully established. + * Gets the timeout until the target endpoint acknowledges accepting the connection request. + *

+ * Note that isn't the same time as the new connection being fully established. An HTTPS connection cannot be considered fully established until the TLS + * handshake has been successfully completed. + *

*

* A timeout value of zero is interpreted as an infinite timeout. *

* - * @return the timeout until a new connection is fully established, defaults to 3 minutes. + * @return the ttimeout until the target endpoint acknowledges accepting the connection request, defaults to 3 minutes. * @see Builder#setConnectTimeout(Timeout) */ public Timeout getConnectTimeout() { From c38b00f8e33c80602e6a2438b8d1123113fee0dc Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Sun, 12 Apr 2026 06:58:16 -0400 Subject: [PATCH 3/3] Fix Javadoc typo --- .../org/apache/hc/client5/http/config/ConnectionConfig.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java index 527dfee84b..d69949f1a4 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java @@ -104,7 +104,7 @@ public Timeout getSocketTimeout() { * A timeout value of zero is interpreted as an infinite timeout. *

* - * @return the ttimeout until the target endpoint acknowledges accepting the connection request, defaults to 3 minutes. + * @return the timeout until the target endpoint acknowledges accepting the connection request, defaults to 3 minutes. * @see Builder#setConnectTimeout(Timeout) */ public Timeout getConnectTimeout() {