com.vmware.vapi.protocol

Class HttpConfiguration.Builder

java.lang.Object

com.vmware.vapi.protocol.HttpConfiguration.Builder

Enclosing class:

HttpConfiguration

public static final class HttpConfiguration.Builder
extends java.lang.Object

Builder class for the HttpConfiguration.

Constructor Summary

Constructors

Constructor and Description
Builder()

Method Summary

Modifier and Type	Method and Description
HttpConfiguration	getConfig() Creates a configuration with all the settings set to this builder instance.
HttpConfiguration.Builder	setConnectTimeout(int connectTimeout) Sets the amount of time the client is going to wait for establishing a connection with the target API endpoint.
HttpConfiguration.Builder	setHeadersProvider(HttpConfiguration.HeadersProvider headersProvider) Sets a callback instance that gets invoked upon each request.
HttpConfiguration.Builder	setIoThreadCount(int ioThreadCount) Defines the number of I/O dispatch threads to be used by the I/O reactor of the third-party HTTP library.
HttpConfiguration.Builder	setKeepAlivePeriod(long keepAlivePeriod) Sets the maximum time a connection is allowed to be kept alive.
HttpConfiguration.Builder	setLibraryType(HttpConfiguration.LibType libraryType) Sets the type of the HTTP library to be used for execution of API requests.
HttpConfiguration.Builder	setMaxConnections(int maxConnections) Sets the maximum number of outstanding TCP connections.
HttpConfiguration.Builder	setMaxResponseSize(int maxResponseSize) Set the maximum allowed size of the content of the response that the client can consume in bytes.
HttpConfiguration.Builder	setProtocol(HttpConfiguration.Protocol protocol) Sets the vAPI Protocol that is used by client to invoke APIs on the server.
HttpConfiguration.Builder	setProxyConfiguration(HttpConfiguration.ProxyConfiguration proxyConfiguration) Sets the proxy configuration object used to configure proxy settings on the client.
HttpConfiguration.Builder	setSoTimeout(int soTimeout) Sets the amount of time (in milliseconds) the client is going to wait for a response before timing out.
HttpConfiguration.Builder	setSslConfiguration(HttpConfiguration.SslConfiguration sslConfig) Sets the SSL configuration for executing request over HTTPs, including trust store for validating server certificate, and optionally key store for presenting client certificate (SSl mutual authentication).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Builder

public Builder()

Method Detail

setLibraryType

public HttpConfiguration.Builder setLibraryType(HttpConfiguration.LibType libraryType)

Sets the type of the HTTP library to be used for execution of API requests.

Default value is HttpConfiguration.LibType.APACHE_HTTP_CLIENT.

Parameters:

libraryType - HTTP library flavor; must not be null

Returns:

this instance

setSslConfiguration

public HttpConfiguration.Builder setSslConfiguration(HttpConfiguration.SslConfiguration sslConfig)

Sets the SSL configuration for executing request over HTTPs, including trust store for validating server certificate, and optionally key store for presenting client certificate (SSl mutual authentication).

This is not required, but if not set, the client will use the default trust-store of the JRE to connect to API endpoints over HTTPs.

Note that the special instance HttpConfiguration.SslConfiguration.SKIP_SSL_INITIALIZATION may be used to completely disable the TLS/SSL initialization.

If the system property org.bouncycastle.fips.approved_only is set to true (case insensitive) the TLS/SSL stack will not be initialized, even if different configuration is provide here.

Parameters:

sslConfig - SSL related settings

Returns:

this instance

setIoThreadCount

public HttpConfiguration.Builder setIoThreadCount(int ioThreadCount)

Defines the number of I/O dispatch threads to be used by the I/O reactor of the third-party HTTP library. Applies only to the following libraries: HttpConfiguration.LibType.APACHE_HTTP_ASYNC_CLIENT.

Defaults to the number of the processors on the machine.

Parameters:

ioThreadCount - number of I/O threads; must be positive

Returns:

this instance

setConnectTimeout

public HttpConfiguration.Builder setConnectTimeout(int connectTimeout)

Sets the amount of time the client is going to wait for establishing a connection with the target API endpoint.

Value of 0 means never timeout (wait forever). Negative values are not allowed.

The default value is 15 000 ms (15 seconds).

Parameters:

connectTimeout - time in milliseconds; must not be negative

Returns:

this instance

setSoTimeout

public HttpConfiguration.Builder setSoTimeout(int soTimeout)

Sets the amount of time (in milliseconds) the client is going to wait for a response before timing out. If the underlying transport protocol is HTTP 1.1, this setting maps directly to SO_TIMEOUT which impact the Socket.read() method.

Value of 0 means never time out (wait forever). Negative values are not allowed.

The default value is 0 (never time out).

Parameters:

soTimeout - time in milliseconds; must not be negative

Returns:

this instance

setMaxConnections

public HttpConfiguration.Builder setMaxConnections(int maxConnections)

Sets the maximum number of outstanding TCP connections.

Default value is 20 connections.

Clients which execute large number of simultaneous API requests need to consider increasing this value to avoid starvation for connections. It is inherent for the HTTP protocol to occupy a TCP connection for the whole timespan of a request/response execution (even if non-blocking I/O is used).

Parameters:

maxConnections - maximum number of connections; must be positive

Returns:

this instance

setMaxResponseSize

public HttpConfiguration.Builder setMaxResponseSize(int maxResponseSize)

Set the maximum allowed size of the content of the response that the client can consume in bytes. It is a helpful option having in mind that the whole response is buffered in-memory. Response content that is larger than the limit will cause a TransportProtocolException at runtime.

The method guarantees that at least this size will be allowed. However, the effective maximum size will be the lowest number which is a power of two and is bigger than or equal to the number that is set. That is, effective limit L = min(2^N), where L >= maxResponseSize.

As an example, setting 2000 bytes will produce an effective limit of 2^11 which is 2048 bytes. Setting 4096 which is 2^12, will not lead to changes and the effective limit will stay 4096 bytes

HttpConfiguration#getMaxResponseSize()} for the effective limit set

When the response content type is HttpConstants.CONTENT_TYPE_STREAM_JSON or HttpConstants.CONTENT_TYPE_FRAMED maxResponseSize designates the maximum size of a single frame

Default value is bytes

Parameters:

maxResponseSize - The maximum allowed size of the response content in bytes.

setKeepAlivePeriod

public HttpConfiguration.Builder setKeepAlivePeriod(long keepAlivePeriod)

Sets the maximum time a connection is allowed to be kept alive. A pooled (kept alive after finished reading a HTTP response) connection that was idle for more than the specified period will be discarded and closed (not reused anymore).

Non-positive value for this setting means that the connection can be kept alive indefinitely.

It is highly recommended that a value lower than max idle timeout on the server is used. Otherwise a race is possible between client reusing a kept-alive connection for subsequent request and server closing the same connection due to inactivity. In such cases the client request might fail with network error (connection already closed).

Default value is 45 000 ms (45 seconds).

Parameters:

keepAlivePeriod - the time period in milliseconds.

Returns:

this instance

setHeadersProvider

public HttpConfiguration.Builder setHeadersProvider(HttpConfiguration.HeadersProvider headersProvider)

Sets a callback instance that gets invoked upon each request.

The callback is expected to provide a list of headers to be added to the request.

Exceptions thrown from the callback or from the methods of each HttpConfiguration.Header will propagate and cause the invocation to fail.

Headers reserved for the runtime, that are being returned by the callback, will be skipped.

Parameters:

headersProvider - the callback instance

Returns:

this instance

setProtocol

public HttpConfiguration.Builder setProtocol(HttpConfiguration.Protocol protocol)

Sets the vAPI Protocol that is used by client to invoke APIs on the server.

Default value is HttpConfiguration.Protocol.VAPI_JSON_RPC_1_0.

Parameters:

protocol - vAPI Protocol; must not be null.

Returns:

this instance

setProxyConfiguration

public HttpConfiguration.Builder setProxyConfiguration(HttpConfiguration.ProxyConfiguration proxyConfiguration)

Sets the proxy configuration object used to configure proxy settings on the client.

Parameters:

proxyConfiguration - is the ProxyConfiguration instance.

Returns:

this instace.

getConfig

public HttpConfiguration getConfig()

Creates a configuration with all the settings set to this builder instance.

Returns:

immutable HttpConfiguration

Throws:

java.lang.IllegalStateException - if the combination of settings is not supported