Apache
/
httpcomponents-client
mirror of https://github.com/apache/httpcomponents-client.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Move javadocs to Builder classes

This commit is contained in:
Richard Hernandez 2019-08-22 17:56:12 -07:00 committed by Oleg Kalnichevski
parent c9dc2c9281
commit 08b35c7f67
1 changed files with 137 additions and 138 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

275
httpclient5/src/main/java/org/apache/hc/client5/http/config/RequestConfig.java
View File

@ -102,204 +102,98 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* Determines whether the 'Expect: 100-Continue' handshake is enabled * @see Builder#setExpectContinueEnabled(boolean)
* for entity enclosing methods. The purpose of the 'Expect: 100-Continue'
* handshake is to allow a client that is sending a request message with
* a request body to determine if the origin server is willing to
* accept the request (based on the request headers) before the client
* sends the request body.
* <p>
* The use of the 'Expect: 100-continue' handshake can result in
* a noticeable performance improvement for entity enclosing requests
* (such as POST and PUT) that require the target server's
* authentication.
* </p>
* <p>
* 'Expect: 100-continue' handshake should be used with caution, as it
* may cause problems with HTTP servers and proxies that do not support
* HTTP/1.1 protocol.
* </p>
* <p>
* Default: {@code false}
* </p>
*/ */
public boolean isExpectContinueEnabled() { public boolean isExpectContinueEnabled() {
return expectContinueEnabled; return expectContinueEnabled;
} }
/** /**
* Returns HTTP proxy to be used for request execution. * @see Builder#setProxy(HttpHost)
* <p>
* Default: {@code null}
* </p>
*/ */
public HttpHost getProxy() { public HttpHost getProxy() {
return proxy; return proxy;
} }
/** /**
* Determines the name of the cookie specification to be used for HTTP state * @see Builder#setCookieSpec(String)
* management.
* <p>
* Default: {@code null}
* </p>
*/ */
public String getCookieSpec() { public String getCookieSpec() {
return cookieSpec; return cookieSpec;
} }
/** /**
* Determines whether redirects should be handled automatically. * @see Builder#setRedirectsEnabled(boolean)
* <p>
* Default: {@code true}
* </p>
*/ */
public boolean isRedirectsEnabled() { public boolean isRedirectsEnabled() {
return redirectsEnabled; return redirectsEnabled;
} }
/** /**
* Determines whether circular redirects (redirects to the same location) should * @see Builder#setCircularRedirectsAllowed(boolean)
* be allowed. The HTTP spec is not sufficiently clear whether circular redirects
* are permitted, therefore optionally they can be enabled
* <p>
* Default: {@code false}
* </p>
*/ */
public boolean isCircularRedirectsAllowed() { public boolean isCircularRedirectsAllowed() {
return circularRedirectsAllowed; return circularRedirectsAllowed;
} }
/** /**
* Returns the maximum number of redirects to be followed. The limit on number * @see Builder#setMaxRedirects(int)
* of redirects is intended to prevent infinite loops.
* <p>
* Default: {@code 50}
* </p>
*/ */
public int getMaxRedirects() { public int getMaxRedirects() {
return maxRedirects; return maxRedirects;
} }
/** /**
* Determines whether authentication should be handled automatically. * @see Builder#setAuthenticationEnabled(boolean)
* <p>
* Default: {@code true}
* </p>
*/ */
public boolean isAuthenticationEnabled() { public boolean isAuthenticationEnabled() {
return authenticationEnabled; return authenticationEnabled;
} }
/** /**
* Determines the order of preference for supported authentication schemes * @see Builder#setTargetPreferredAuthSchemes(Collection)
* when authenticating with the target host.
* <p>
* Default: {@code null}
* </p>
*/ */
public Collection<String> getTargetPreferredAuthSchemes() { public Collection<String> getTargetPreferredAuthSchemes() {
return targetPreferredAuthSchemes; return targetPreferredAuthSchemes;
} }
/** /**
* Determines the order of preference for supported authentication schemes * @see Builder#setProxyPreferredAuthSchemes(Collection)
* when authenticating with the proxy host.
* <p>
* Default: {@code null}
* </p>
*/ */
public Collection<String> getProxyPreferredAuthSchemes() { public Collection<String> getProxyPreferredAuthSchemes() {
return proxyPreferredAuthSchemes; return proxyPreferredAuthSchemes;
} }
/** /**
* Returns the connection lease request timeout used when requesting * @see Builder#setConnectionRequestTimeout(Timeout)
* a connection from the connection manager.
* <p>
* A timeout value of zero is interpreted as an infinite timeout.
* </p>
* <p>
* Default: 3 minutes.
* </p>
*/ */
public Timeout getConnectionRequestTimeout() { public Timeout getConnectionRequestTimeout() {
return connectionRequestTimeout; return connectionRequestTimeout;
} }
/** /**
* Determines the timeout until a new connection is fully established. * @see Builder#setConnectTimeout(Timeout)
* This may also include transport security negotiation exchanges
* such as {@code SSL} or {@code TLS} protocol negotiation).
* <p>
* A timeout value of zero is interpreted as an infinite timeout.
* </p>
* <p>
* Default: 3 minutes
* </p>
*/ */
public Timeout getConnectTimeout() { public Timeout getConnectTimeout() {
return connectTimeout; return connectTimeout;
} }
/** /**
* Determines the timeout until arrival of a response from the opposite * @see Builder#setResponseTimeout(Timeout)
* endpoint.
* <p>
* A timeout value of zero is interpreted as an infinite timeout.
* </p>
* <p>
* Please note that response timeout may be unsupported by
* HTTP transports with message multiplexing.
* </p>
* <p>
* Default: {@code null}
* </p>
*
* @since 5.0
*/ */
public Timeout getResponseTimeout() { public Timeout getResponseTimeout() {
return responseTimeout; return responseTimeout;
} }
/** /**
* Determines whether the target server is requested to compress content. * @see Builder#setContentCompressionEnabled(boolean)
* <p>
* Default: {@code true}
* </p>
*
* @since 4.5
*/ */
public boolean isContentCompressionEnabled() { public boolean isContentCompressionEnabled() {
return contentCompressionEnabled; return contentCompressionEnabled;
} }
/** /**
* Determines whether request cancellation, such as through {@code * @see Builder#setHardCancellationEnabled(boolean)
* Future#cancel(boolean)}, should kill the underlying connection. If this
* option is set to false, the client will attempt to preserve the
* underlying connection by allowing the request to complete in the
* background, discarding the response.
* <p>
* Note that when this option is {@code true}, cancelling a request may
* cause other requests to fail, if they are waiting to use the same
* connection.
* </p>
* <p>
* On HTTP/2, this option has no effect. Request cancellation will always
* result in the stream being cancelled with a {@code RST_STREAM}. This
* has no effect on connection reuse.
* </p>
* <p>
* On non-asynchronous clients, this option has no effect. Request
* cancellation, such as through {@code HttpUriRequestBase#cancel()}, will
* always kill the underlying connection.
* </p>
* <p>
* Default: {@code true}
* </p>
*
* @since 5.0
*/ */
public boolean isHardCancellationEnabled() { public boolean isHardCancellationEnabled() {
return hardCancellationEnabled; return hardCancellationEnabled;
@ -381,7 +275,26 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #isExpectContinueEnabled() * Determines whether the 'Expect: 100-Continue' handshake is enabled
* for entity enclosing methods. The purpose of the 'Expect: 100-Continue'
* handshake is to allow a client that is sending a request message with
* a request body to determine if the origin server is willing to
* accept the request (based on the request headers) before the client
* sends the request body.
* <p>
* The use of the 'Expect: 100-continue' handshake can result in
* a noticeable performance improvement for entity enclosing requests
* (such as POST and PUT) that require the target server's
* authentication.
* </p>
* <p>
* 'Expect: 100-continue' handshake should be used with caution, as it
* may cause problems with HTTP servers and proxies that do not support
* HTTP/1.1 protocol.
* </p>
* <p>
* Default: {@code false}
* </p>
*/ */
public Builder setExpectContinueEnabled(final boolean expectContinueEnabled) { public Builder setExpectContinueEnabled(final boolean expectContinueEnabled) {
this.expectContinueEnabled = expectContinueEnabled; this.expectContinueEnabled = expectContinueEnabled;
@ -389,7 +302,10 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #getProxy() * Returns HTTP proxy to be used for request execution.
* <p>
* Default: {@code null}
* </p>
*/ */
public Builder setProxy(final HttpHost proxy) { public Builder setProxy(final HttpHost proxy) {
this.proxy = proxy; this.proxy = proxy;
@ -397,7 +313,11 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #getCookieSpec() * Determines the name of the cookie specification to be used for HTTP state
* management.
* <p>
* Default: {@code null}
* </p>
*/ */
public Builder setCookieSpec(final String cookieSpec) { public Builder setCookieSpec(final String cookieSpec) {
this.cookieSpec = cookieSpec; this.cookieSpec = cookieSpec;
@ -405,7 +325,10 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #isRedirectsEnabled() * Determines whether redirects should be handled automatically.
* <p>
* Default: {@code true}
* </p>
*/ */
public Builder setRedirectsEnabled(final boolean redirectsEnabled) { public Builder setRedirectsEnabled(final boolean redirectsEnabled) {
this.redirectsEnabled = redirectsEnabled; this.redirectsEnabled = redirectsEnabled;
@ -413,7 +336,12 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #isCircularRedirectsAllowed() * Determines whether circular redirects (redirects to the same location) should
* be allowed. The HTTP spec is not sufficiently clear whether circular redirects
* are permitted, therefore optionally they can be enabled
* <p>
* Default: {@code false}
* </p>
*/ */
public Builder setCircularRedirectsAllowed(final boolean circularRedirectsAllowed) { public Builder setCircularRedirectsAllowed(final boolean circularRedirectsAllowed) {
this.circularRedirectsAllowed = circularRedirectsAllowed; this.circularRedirectsAllowed = circularRedirectsAllowed;
@ -421,7 +349,11 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #getMaxRedirects() * Returns the maximum number of redirects to be followed. The limit on number
* of redirects is intended to prevent infinite loops.
* <p>
* Default: {@code 50}
* </p>
*/ */
public Builder setMaxRedirects(final int maxRedirects) { public Builder setMaxRedirects(final int maxRedirects) {
this.maxRedirects = maxRedirects; this.maxRedirects = maxRedirects;
@ -429,7 +361,10 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #isAuthenticationEnabled() * Determines whether authentication should be handled automatically.
* <p>
* Default: {@code true}
* </p>
*/ */
public Builder setAuthenticationEnabled(final boolean authenticationEnabled) { public Builder setAuthenticationEnabled(final boolean authenticationEnabled) {
this.authenticationEnabled = authenticationEnabled; this.authenticationEnabled = authenticationEnabled;
@ -437,7 +372,11 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #getTargetPreferredAuthSchemes() * Determines the order of preference for supported authentication schemes
* when authenticating with the target host.
* <p>
* Default: {@code null}
* </p>
*/ */
public Builder setTargetPreferredAuthSchemes(final Collection<String> targetPreferredAuthSchemes) { public Builder setTargetPreferredAuthSchemes(final Collection<String> targetPreferredAuthSchemes) {
this.targetPreferredAuthSchemes = targetPreferredAuthSchemes; this.targetPreferredAuthSchemes = targetPreferredAuthSchemes;
@ -445,15 +384,25 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #getProxyPreferredAuthSchemes() * Determines the order of preference for supported authentication schemes
* when authenticating with the proxy host.
* <p>
* Default: {@code null}
* </p>
*/ */
public Builder setProxyPreferredAuthSchemes(final Collection<String> proxyPreferredAuthSchemes) { public Builder setProxyPreferredAuthSchemes(final Collection<String> proxyPreferredAuthSchemes) {
this.proxyPreferredAuthSchemes = proxyPreferredAuthSchemes; this.proxyPreferredAuthSchemes = proxyPreferredAuthSchemes;
return this; return this;
} }
/** /**
* @see #getConnectionRequestTimeout() * Returns the connection lease request timeout used when requesting
* a connection from the connection manager.
* <p>
* A timeout value of zero is interpreted as an infinite timeout.
* </p>
* <p>
* Default: 3 minutes.
* </p>
*/ */
public Builder setConnectionRequestTimeout(final Timeout connectionRequestTimeout) { public Builder setConnectionRequestTimeout(final Timeout connectionRequestTimeout) {
this.connectionRequestTimeout = connectionRequestTimeout; this.connectionRequestTimeout = connectionRequestTimeout;
@ -461,7 +410,7 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #getConnectionRequestTimeout() * @see #setConnectionRequestTimeout(Timeout)
*/ */
public Builder setConnectionRequestTimeout(final long connectionRequestTimeout, final TimeUnit timeUnit) { public Builder setConnectionRequestTimeout(final long connectionRequestTimeout, final TimeUnit timeUnit) {
this.connectionRequestTimeout = Timeout.of(connectionRequestTimeout, timeUnit); this.connectionRequestTimeout = Timeout.of(connectionRequestTimeout, timeUnit);
@ -469,7 +418,15 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #getConnectTimeout() * Determines the timeout until a new connection is fully established.
* This may also include transport security negotiation exchanges
* such as {@code SSL} or {@code TLS} protocol negotiation).
* <p>
* A timeout value of zero is interpreted as an infinite timeout.
* </p>
* <p>
* Default: 3 minutes
* </p>
*/ */
public Builder setConnectTimeout(final Timeout connectTimeout) { public Builder setConnectTimeout(final Timeout connectTimeout) {
this.connectTimeout = connectTimeout; this.connectTimeout = connectTimeout;
@ -477,7 +434,7 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #getConnectTimeout() * @see #setConnectTimeout(Timeout)
*/ */
public Builder setConnectTimeout(final long connectTimeout, final TimeUnit timeUnit) { public Builder setConnectTimeout(final long connectTimeout, final TimeUnit timeUnit) {
this.connectTimeout = Timeout.of(connectTimeout, timeUnit); this.connectTimeout = Timeout.of(connectTimeout, timeUnit);
@ -485,7 +442,20 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #getResponseTimeout() * Determines the timeout until arrival of a response from the opposite
* endpoint.
* <p>
* A timeout value of zero is interpreted as an infinite timeout.
* </p>
* <p>
* Please note that response timeout may be unsupported by
* HTTP transports with message multiplexing.
* </p>
* <p>
* Default: {@code null}
* </p>
*
* @since 5.0
*/ */
public Builder setResponseTimeout(final Timeout responseTimeout) { public Builder setResponseTimeout(final Timeout responseTimeout) {
this.responseTimeout = responseTimeout; this.responseTimeout = responseTimeout;
@ -493,7 +463,7 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #getResponseTimeout() * @see #setResponseTimeout(Timeout)
*/ */
public Builder setResponseTimeout(final long responseTimeout, final TimeUnit timeUnit) { public Builder setResponseTimeout(final long responseTimeout, final TimeUnit timeUnit) {
this.responseTimeout = Timeout.of(responseTimeout, timeUnit); this.responseTimeout = Timeout.of(responseTimeout, timeUnit);
@ -501,7 +471,12 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #isContentCompressionEnabled() * Determines whether the target server is requested to compress content.
* <p>
* Default: {@code true}
* </p>
*
* @since 4.5
*/ */
public Builder setContentCompressionEnabled(final boolean contentCompressionEnabled) { public Builder setContentCompressionEnabled(final boolean contentCompressionEnabled) {
this.contentCompressionEnabled = contentCompressionEnabled; this.contentCompressionEnabled = contentCompressionEnabled;
@ -509,7 +484,31 @@ public class RequestConfig implements Cloneable {
} }
/** /**
* @see #isHardCancellationEnabled() * Determines whether request cancellation, such as through {@code
* Future#cancel(boolean)}, should kill the underlying connection. If this
* option is set to false, the client will attempt to preserve the
* underlying connection by allowing the request to complete in the
* background, discarding the response.
* <p>
* Note that when this option is {@code true}, cancelling a request may
* cause other requests to fail, if they are waiting to use the same
* connection.
* </p>
* <p>
* On HTTP/2, this option has no effect. Request cancellation will always
* result in the stream being cancelled with a {@code RST_STREAM}. This
* has no effect on connection reuse.
* </p>
* <p>
* On non-asynchronous clients, this option has no effect. Request
* cancellation, such as through {@code HttpUriRequestBase#cancel()}, will
* always kill the underlying connection.
* </p>
* <p>
* Default: {@code true}
* </p>
*
* @since 5.0
*/ */
public Builder setHardCancellationEnabled(final boolean hardCancellationEnabled) { public Builder setHardCancellationEnabled(final boolean hardCancellationEnabled) {
this.hardCancellationEnabled = hardCancellationEnabled; this.hardCancellationEnabled = hardCancellationEnabled;