Skip to content

Add missing Javadoc for ConnectionConfig #820

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
garydgregory merged 3 commits into from
Apr 12, 2026
+86 −3
Merged

Add missing Javadoc for ConnectionConfig #820

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
77670c6
Add missing Javadoc for ConnectionConfig
garydgregory Apr 11, 2026
dbb960a
Adjust text after PR review.
garydgregory Apr 11, 2026
c38b00f
Fix Javadoc typo
garydgregory Apr 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 82 additions & 3 deletions httpclient5/src/main/java/org/apache/hc/client5/http/config/ConnectionConfig.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,16 @@ public class ConnectionConfig implements Cloneable {

private static final Timeout DEFAULT_CONNECT_TIMEOUT = Timeout.ofMinutes(3);

/**
* The default connection configuration.
* <ul>
* <li>Timeout connectTimeout: 3 minutes</li>
* <li>Timeout socketTimeout: {@code null} (undefined)</li>
* <li>Timeout idleTimeout: {@code null} (undefined)</li>
* <li>TimeValue validateAfterInactivity: {@code null} (undefined)</li>
* <li>TimeValue timeToLive: {@code null} (undefined)</li>
* </ul>
*/
public static final ConnectionConfig DEFAULT = new Builder().build();

private final Timeout connectTimeout;
Expand Down Expand Up @@ -74,34 +84,56 @@ 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() {
return socketTimeout;
}

/**
* Gets the timeout until a new connection is fully established.
* <p>
* A timeout value of zero is interpreted as an infinite timeout.
* </p>
*
* @return the timeout until a new connection is fully established, defaults to 3 minutes.
Copy link
Copy Markdown
Member

@ok2c ok2c Apr 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@garydgregory Can we re-phrase this statement a little? Technically the connection timeout is a timeout until the target endpoint acknowledgement it accepts the connection request, not until the new connection is fully established. For instance an HTTPS connection cannot be considered fully established until the TLS handshake has been successfully completed.

Very nice otherwise.

Copy link
Copy Markdown
Member Author

@garydgregory garydgregory Apr 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TY. Done with dbb960a

* @see Builder#setConnectTimeout(Timeout)
*/
public Timeout getConnectTimeout() {
return connectTimeout;
}

/**
* Gets the maximum period of idleness for a connection.
* <p>
* Implementations can use this value to discard connections that have been idle for too long.
* </p>
*
* @return the maximum period of idleness for a connection, defaults to null.
* @see Builder#setIdleTimeout(Timeout)
*/
public Timeout getIdleTimeout() {
return idleTimeout;
}

/**
* 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() {
return validateAfterInactivity;
}

/**
* 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() {
Expand All @@ -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())
Expand All @@ -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;
Expand All @@ -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)
*/
Expand All @@ -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.
* <p>
Expand All @@ -174,6 +224,7 @@ public Builder setSocketTimeout(final int soTimeout, final TimeUnit timeUnit) {
* Default: {@code null} (undefined)
* </p>
*
* @param soTimeout The default socket timeout value for I/O operations.
* @return this instance.
*/
public Builder setSocketTimeout(final Timeout soTimeout) {
Expand All @@ -182,14 +233,15 @@ 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.
* <p>
* A timeout value of zero is interpreted as an infinite timeout.
* </p>
* <p>
* Default: 3 minutes
* </p>
*
* @param connectTimeout The timeout until a new connection is fully established.
* @return this instance.
*/
public Builder setConnectTimeout(final Timeout connectTimeout) {
Expand All @@ -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)
*/
Expand All @@ -217,6 +273,7 @@ public Builder setConnectTimeout(final long connectTimeout, final TimeUnit timeU
* Default: {@code null} (undefined)
* </p>
*
* @param idleTimeout The maximum period of idleness for a connection.
* @return this instance.
*
* @since 5.6
Expand All @@ -227,6 +284,13 @@ public Builder setIdleTimeout(final Timeout idleTimeout) {
}

/**
* Sets the maximum period of idleness for a connection.
* <p>
* Connections that are idle for longer than {@code idleTimeout} are no longer eligible for reuse.
* </p>
*
* @param idleTimeout The maximum period of idleness for a connection.
* @param timeUnit
* @return this instance.
* @see #setIdleTimeout(Timeout)
*/
Expand All @@ -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.
* <p>
* Default: {@code null} (undefined)
* </p>
*
* @param validateAfterInactivity The period of inactivity after which persistent connections must be re-validated.
* @return this instance.
*/
public Builder setValidateAfterInactivity(final TimeValue validateAfterInactivity) {
Expand All @@ -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)
*/
Expand All @@ -265,6 +334,7 @@ public Builder setValidateAfterInactivity(final long validateAfterInactivity, fi
* Default: {@code null} (undefined)
* </p>
*
* @param timeToLive The total span of time connections can be kept alive or execute requests.
* @return this instance.
*/
public Builder setTimeToLive(final TimeValue timeToLive) {
Expand All @@ -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)
*/
Expand All @@ -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,
Expand Down
Loading