From 2ec71c7685c3f66e1514171e3d6c24eb061bf39c Mon Sep 17 00:00:00 2001 From: ChangYong Date: Sat, 23 Aug 2025 20:33:14 +0900 Subject: [PATCH 1/4] Clarify Javadoc for responseTimeout and socketTimeout interaction --- .../client5/http/config/ConnectionConfig.java | 14 +++++++++-- .../hc/client5/http/config/RequestConfig.java | 24 ++++++++++--------- 2 files changed, 25 insertions(+), 13 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 b372d461aa..0571a572ff 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 @@ -149,9 +149,19 @@ public Builder setSocketTimeout(final int soTimeout, final TimeUnit timeUnit) { } /** - * Determines the default socket timeout value for I/O operations. + * Determines 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. *

- * Default: {@code null} (undefined) + * This value serves as the baseline timeout applied when a connection is first + * created and managed by the connection pool. + *

+ *

+ * Please note: in classic (blocking) I/O execution, if a request-level + * {@link org.apache.hc.client5.http.config.RequestConfig.Builder#setResponseTimeout} + * is specified, that value will temporarily override this default socket + * timeout for the duration of the request. If no response timeout is set, the + * current socket timeout of the reused connection remains in effect. *

* * @return this instance. diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java index f13d940fe3..756b036424 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java @@ -533,23 +533,25 @@ public Builder setConnectTimeout(final long connectTimeout, final TimeUnit timeU } /** - * Determines the timeout until arrival of a response from the opposite - * endpoint. - *

+ * Determines the timeout until arrival of a response from the opposite endpoint. * A timeout value of zero is interpreted as an infinite timeout. - *

*

- * Please note that response timeout may be unsupported by - * HTTP transports with message multiplexing. + * Please note that response timeout may be unsupported by HTTP transports with + * message multiplexing. *

*

- * Please note that response timeout is not a deadline. Its absolute value - * can be exceeded, for example, in case of automatic request re-execution. - * Please make sure the automatic request re-execution policy has been - * configured appropriately. + * Please note that response timeout is not a deadline. Its absolute value can + * be exceeded, for example, in case of automatic request re-execution. Please + * make sure the automatic request re-execution policy has been configured + * appropriately. *

*

- * Default: {@code null} + * In classic (blocking) I/O execution, if this value is set, it will be applied + * as the connection's {@code SO_TIMEOUT} for the duration of the request. This + * effectively overrides any default socket timeout configured via + * {@link org.apache.hc.client5.http.config.ConnectionConfig.Builder#setSocketTimeout}. + * If unset ({@code null}), the existing socket timeout of the reused connection + * remains in effect. *

* * @return this instance. From caa748a280e6de6f4717f29a472b00d28d3ef33e Mon Sep 17 00:00:00 2001 From: ChangYong Date: Mon, 25 Aug 2025 07:58:55 +0900 Subject: [PATCH 2/4] Revert formatting changes --- .../client5/http/config/ConnectionConfig.java | 3 +++ .../hc/client5/http/config/RequestConfig.java | 20 ++++++++++++------- 2 files changed, 16 insertions(+), 7 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 0571a572ff..2611f57465 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 @@ -163,6 +163,9 @@ public Builder setSocketTimeout(final int soTimeout, final TimeUnit timeUnit) { * timeout for the duration of the request. If no response timeout is set, the * current socket timeout of the reused connection remains in effect. *

+ *

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

* * @return this instance. */ diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java index 756b036424..ab64297b83 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java @@ -533,17 +533,20 @@ public Builder setConnectTimeout(final long connectTimeout, final TimeUnit timeU } /** - * Determines the timeout until arrival of a response from the opposite endpoint. + * Determines the timeout until arrival of a response from the opposite + * endpoint. + *

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

*

- * Please note that response timeout may be unsupported by HTTP transports with - * message multiplexing. + * Please note that response timeout may be unsupported by + * HTTP transports with message multiplexing. *

*

- * Please note that response timeout is not a deadline. Its absolute value can - * be exceeded, for example, in case of automatic request re-execution. Please - * make sure the automatic request re-execution policy has been configured - * appropriately. + * Please note that response timeout is not a deadline. Its absolute value + * can be exceeded, for example, in case of automatic request re-execution. + * Please make sure the automatic request re-execution policy has been + * configured appropriately. *

*

* In classic (blocking) I/O execution, if this value is set, it will be applied @@ -553,6 +556,9 @@ public Builder setConnectTimeout(final long connectTimeout, final TimeUnit timeU * If unset ({@code null}), the existing socket timeout of the reused connection * remains in effect. *

+ *

+ * Default: {@code null} + *

* * @return this instance. * @since 5.0 From bcf49661790cd78855e79825e62d5aeb87d8ab3b Mon Sep 17 00:00:00 2001 From: ChangYong Date: Mon, 25 Aug 2025 08:19:33 +0900 Subject: [PATCH 3/4] Address review comments --- .../client5/http/config/ConnectionConfig.java | 13 ++++--------- .../hc/client5/http/config/RequestConfig.java | 17 +++++------------ 2 files changed, 9 insertions(+), 21 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 2611f57465..478ee86a1c 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 @@ -153,15 +153,10 @@ public Builder setSocketTimeout(final int soTimeout, final TimeUnit timeUnit) { * connections created by this configuration. * A timeout value of zero is interpreted as an infinite timeout. *

- * This value serves as the baseline timeout applied when a connection is first - * created and managed by the connection pool. - *

- *

- * Please note: in classic (blocking) I/O execution, if a request-level - * {@link org.apache.hc.client5.http.config.RequestConfig.Builder#setResponseTimeout} - * is specified, that value will temporarily override this default socket - * timeout for the duration of the request. If no response timeout is set, the - * current socket timeout of the reused connection remains in effect. + * This value acts as a baseline configured by the I/O layer. It can be + * overridden by settings applied at the connection layer, and in turn may be + * overridden by parameters applied at the protocol layer for the duration of + * a message execution. *

*

* Default: {@code null} (undefined) diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java index ab64297b83..f934ab9742 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java @@ -543,18 +543,11 @@ public Builder setConnectTimeout(final long connectTimeout, final TimeUnit timeU * HTTP transports with message multiplexing. *

*

- * Please note that response timeout is not a deadline. Its absolute value - * can be exceeded, for example, in case of automatic request re-execution. - * Please make sure the automatic request re-execution policy has been - * configured appropriately. - *

- *

- * In classic (blocking) I/O execution, if this value is set, it will be applied - * as the connection's {@code SO_TIMEOUT} for the duration of the request. This - * effectively overrides any default socket timeout configured via - * {@link org.apache.hc.client5.http.config.ConnectionConfig.Builder#setSocketTimeout}. - * If unset ({@code null}), the existing socket timeout of the reused connection - * remains in effect. + * This parameter may override a socket timeout configured at the connection + * or I/O layers for the duration of a message execution. It is not a hard + * deadline; its effective duration can be exceeded, for example, by automatic + * request re-execution policies. Ensure such policies are configured + * appropriately. *

*

* Default: {@code null} From 642075904649c6b104fa0a4edb817e685b9a085d Mon Sep 17 00:00:00 2001 From: ChangYong Date: Mon, 25 Aug 2025 08:26:05 +0900 Subject: [PATCH 4/4] Restore original text --- .../org/apache/hc/client5/http/config/RequestConfig.java | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java index f934ab9742..4dbf1cc8e6 100644 --- a/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java @@ -543,6 +543,12 @@ public Builder setConnectTimeout(final long connectTimeout, final TimeUnit timeU * HTTP transports with message multiplexing. *

*

+ * Please note that response timeout is not a deadline. Its absolute value + * can be exceeded, for example, in case of automatic request re-execution. + * Please make sure the automatic request re-execution policy has been + * configured appropriately. + *

+ *

* This parameter may override a socket timeout configured at the connection * or I/O layers for the duration of a message execution. It is not a hard * deadline; its effective duration can be exceeded, for example, by automatic