ConnectionPolicy Class

Package:

com.microsoft.azure.documentdb

• java.lang.Object
• • com.microsoft.azure.documentdb.ConnectionPolicy

public class ConnectionPolicy

Represents the Connection policy associated with a DocumentClient in the Azure Cosmos DB database service.

Constructor Summary

Constructor	Description
ConnectionPolicy()	Constructor.

Method Summary

Modifier and Type	Method and Description
ConnectionMode	getConnectionMode() Gets the connection mode used in the client.
ConnectionPolicy	GetDefault() Gets the default connection policy.
boolean	getEnableEndpointDiscovery() Gets the flag to enable endpoint discovery for geo-replicated database accounts.
int	getIdleConnectionTimeout() Gets the value of the timeout for an idle connection, the default is 60 seconds.
int	getMaxPoolSize() Gets the value of the connection pool size the client is using.
Integer	getMaxRetryOnThrottledAttempts() Gets the maximum number of retries in the case where the request fails due to a throttle error. This property is deprecated. Please use connectionPolicy.getRetryOptions().getMaxRetryAttemptsOnThrottledRequests() for equivalent functionality.
MediaReadMode	getMediaReadMode() Gets the attachment content (aka media) download mode.
int	getMediaRequestTimeout() Gets or sets Time to wait for response from network peer for attachment content (aka media) operations.
Collection<String>	getPreferredLocations() Gets the preferred locations for geo-replicated database accounts
HttpHost	getProxy() Gets a proxy which will be used when making a request. Default is .
int	getRequestTimeout() Gets the request timeout (time to wait for response from network peer) in seconds.
RetryOptions	getRetryOptions() Gets the retry policy options associated with the DocumentClient instance.
String	getUserAgentSuffix() Gets the value of user-agent suffix.
void	setConnectionMode(ConnectionMode connectionMode) Sets the connection mode used in the client.
void	setEnableEndpointDiscovery(boolean enableEndpointDiscovery) Sets the flag to enable endpoint discovery for geo-replicated database accounts. When EnableEndpointDiscovery is true, the SDK will automatically discover the current write and read regions to ensure requests are sent to the correct region based on the capability of the region and the user's preference. The default value for this property is true indicating endpoint discovery is enabled.
void	setIdleConnectionTimeout(int idleConnectionTimeout) sets the value of the timeout for an idle connection. After that time, the connection will be automatically closed.
void	setMaxPoolSize(int maxPoolSize) Sets the value of the connection pool size of the httpclient, the default is 100.
void	setMaxRetryOnThrottledAttempts(Integer maxRetryOnThrottledAttempts) Sets the maximum number of retries in the case where the request fails due to a throttle error. When a client is sending request faster than the request rate limit imposed by the service, the service will return HttpStatusCode 429 (Too Many Request) to throttle the client. The current implementation in the SDK will then wait for the amount of time the service tells it to wait and retry after the time has elapsed. The default value is 9. This means in the case where the request is throttled, the same request will be issued for a maximum of 10 times to the server before an error is returned to the application. This property is deprecated. Please use connectionPolicy.getRetryOptions().setMaxRetryAttemptsOnThrottledRequests() for equivalent functionality.
void	setMediaReadMode(MediaReadMode mediaReadMode) Sets the attachment content (aka media) download mode.
void	setMediaRequestTimeout(int mediaRequestTimeout) Gets or sets Time to wait for response from network peer for attachment content (aka media) operations.
void	setPreferredLocations(Collection<String> preferredLocations) Sets the preferred locations for geo-replicated database accounts. For example, "East US" as the preferred location. When EnableEndpointDiscovery is true and PreferredRegions is non-empty, the SDK will prefer to use the locations in the collection in the order they are specified to perform operations. If EnableEndpointDiscovery is set to false, this property is ignored.
void	setProxy(HttpHost proxy) Sets a proxy which will be used when making a request. Default is .
void	setRequestTimeout(int requestTimeout) Sets the request timeout (time to wait for response from network peer) in seconds.
void	setRetryOptions(RetryOptions retryOptions) Sets the retry policy options associated with the DocumentClient instance. Properties in the RetryOptions class allow application to customize the built-in retry policies. This property is optional. When it's not set, the SDK uses the default values for configuring the retry policies. See RetryOptions class for more details.
void	setUserAgentSuffix(String userAgentSuffix) sets the value of the user-agent suffix.
String	toString()

Constructor Details

ConnectionPolicy

public ConnectionPolicy()

Constructor.

Method Details

getConnectionMode

public ConnectionMode getConnectionMode()

Gets the connection mode used in the client.

Returns:

the connection mode.

GetDefault

public static ConnectionPolicy GetDefault()

Gets the default connection policy.

Returns:

the default connection policy.

getEnableEndpointDiscovery

public boolean getEnableEndpointDiscovery()

Gets the flag to enable endpoint discovery for geo-replicated database accounts.

Returns:

whether endpoint discovery is enabled.

getIdleConnectionTimeout

public int getIdleConnectionTimeout()

Gets the value of the timeout for an idle connection, the default is 60 seconds.

Returns:

Idle connection timeout.

getMaxPoolSize

public int getMaxPoolSize()

Gets the value of the connection pool size the client is using.

Returns:

connection pool size.

getMaxRetryOnThrottledAttempts

public Integer getMaxRetryOnThrottledAttempts()

Gets the maximum number of retries in the case where the request fails due to a throttle error.

This property is deprecated. Please use connectionPolicy.getRetryOptions().getMaxRetryAttemptsOnThrottledRequests() for equivalent functionality.

Returns:

maximum number of retry attempts.

getMediaReadMode

public MediaReadMode getMediaReadMode()

Gets the attachment content (aka media) download mode.

Returns:

the media read mode.

getMediaRequestTimeout

public int getMediaRequestTimeout()

Gets or sets Time to wait for response from network peer for attachment content (aka media) operations.

Returns:

the media request timeout in seconds.

getPreferredLocations

public Collection getPreferredLocations()

Gets the preferred locations for geo-replicated database accounts

Returns:

the list of preferred location.

getProxy

public HttpHost getProxy()

Gets a proxy which will be used when making a request. Default is .

Returns:

A proxy to use when making a request.

getRequestTimeout

public int getRequestTimeout()

Gets the request timeout (time to wait for response from network peer) in seconds.

Returns:

the request timeout in seconds.

getRetryOptions

public RetryOptions getRetryOptions()

Gets the retry policy options associated with the DocumentClient instance.

Returns:

the RetryOptions instance.

getUserAgentSuffix

public String getUserAgentSuffix()

Gets the value of user-agent suffix.

Returns:

the value of user-agent suffix.

setConnectionMode

public void setConnectionMode(ConnectionMode connectionMode)

Sets the connection mode used in the client.

Parameters:

connectionMode - the connection mode.

setEnableEndpointDiscovery

public void setEnableEndpointDiscovery(boolean enableEndpointDiscovery)

Sets the flag to enable endpoint discovery for geo-replicated database accounts.

When EnableEndpointDiscovery is true, the SDK will automatically discover the current write and read regions to ensure requests are sent to the correct region based on the capability of the region and the user's preference.

The default value for this property is true indicating endpoint discovery is enabled.

Parameters:

enableEndpointDiscovery - true if EndpointDiscovery is enabled.

setIdleConnectionTimeout

public void setIdleConnectionTimeout(int idleConnectionTimeout)

sets the value of the timeout for an idle connection. After that time, the connection will be automatically closed.

Parameters:

idleConnectionTimeout - the timeout for an idle connection in seconds.

setMaxPoolSize

public void setMaxPoolSize(int maxPoolSize)

Sets the value of the connection pool size of the httpclient, the default is 100.

Parameters:

maxPoolSize - The value of the connection pool size the httpclient is using.

setMaxRetryOnThrottledAttempts

public void setMaxRetryOnThrottledAttempts(Integer maxRetryOnThrottledAttempts)

Sets the maximum number of retries in the case where the request fails due to a throttle error.

When a client is sending request faster than the request rate limit imposed by the service, the service will return HttpStatusCode 429 (Too Many Request) to throttle the client. The current implementation in the SDK will then wait for the amount of time the service tells it to wait and retry after the time has elapsed.

The default value is 9. This means in the case where the request is throttled, the same request will be issued for a maximum of 10 times to the server before an error is returned to the application.

This property is deprecated. Please use connectionPolicy.getRetryOptions().setMaxRetryAttemptsOnThrottledRequests() for equivalent functionality.

Parameters:

maxRetryOnThrottledAttempts - the max number of retry attempts on failed requests.

setMediaReadMode

public void setMediaReadMode(MediaReadMode mediaReadMode)

Sets the attachment content (aka media) download mode.

Parameters:

mediaReadMode - the media read mode.

setMediaRequestTimeout

public void setMediaRequestTimeout(int mediaRequestTimeout)

Gets or sets Time to wait for response from network peer for attachment content (aka media) operations.

Parameters:

mediaRequestTimeout - the media request timeout in seconds.

setPreferredLocations

public void setPreferredLocations(Collection preferredLocations)

Sets the preferred locations for geo-replicated database accounts. For example, "East US" as the preferred location.

When EnableEndpointDiscovery is true and PreferredRegions is non-empty, the SDK will prefer to use the locations in the collection in the order they are specified to perform operations.

If EnableEndpointDiscovery is set to false, this property is ignored.

Parameters:

preferredLocations - the list of preferred locations.

setProxy

public void setProxy(HttpHost proxy)

Sets a proxy which will be used when making a request. Default is .

Parameters:

proxy - A proxy to use when making a request.

setRequestTimeout

public void setRequestTimeout(int requestTimeout)

Sets the request timeout (time to wait for response from network peer) in seconds.

Parameters:

requestTimeout - the request timeout in seconds.

setRetryOptions

public void setRetryOptions(RetryOptions retryOptions)

Sets the retry policy options associated with the DocumentClient instance.

Properties in the RetryOptions class allow application to customize the built-in retry policies. This property is optional. When it's not set, the SDK uses the default values for configuring the retry policies. See RetryOptions class for more details.

Parameters:

retryOptions - the RetryOptions instance.

setUserAgentSuffix

public void setUserAgentSuffix(String userAgentSuffix)

sets the value of the user-agent suffix.

Parameters:

userAgentSuffix - The value to be appended to the user-agent header, this is used for monitoring purposes.

toString

public String toString()