+ * 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 the target endpoint acknowledges accepting the connection request, defaults to 3 minutes. * @see Builder#setConnectTimeout(Timeout) */ public Timeout getConnectTimeout() { @@ -88,6 +112,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 +125,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 +135,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 +162,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 +185,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 +202,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 +215,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 +228,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 +237,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 +245,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 +254,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 +277,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 +288,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 +304,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 +320,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 +338,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 +347,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 +359,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,