ConnectionPolicy Class

Package:

com.microsoft.azure.documentdb

Maven Artifact:

com.microsoft.azure:azure-documentdb:2.4.7

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

public final 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
static ConnectionPolicy	GetDefault() Gets the default connection policy.
ConnectionMode	getConnectionMode() Gets the connection mode used in the client.
int	getDirectRequestTimeout() Gets the direct mode request timeout (time to wait for response from network peer) in seconds This only applies to requests that talk directly to the backend.
boolean	getEnableEndpointDiscovery() Gets the flag to enable endpoint discovery for geo-replicated database accounts.
boolean	getHandleServiceUnavailableFromProxy() Gets the flag to handle service unavailable errors returned without a service version header, by a proxy.
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.
java.lang.Integer	getMaxRetryOnThrottledAttempts() Gets the maximum number of retries in the case where the request fails due to a throttle error.
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.
java.util.Collection<java.lang.String>	getPreferredLocations() Gets the preferred locations for geo-replicated database accounts
org.apache.http.HttpHost	getProxy() Gets a proxy which will be used when making a request.
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.
java.lang.String	getUserAgentSuffix() Gets the value of user-agent suffix.
boolean	isUsingMultipleWriteLocations() Gets the flag to enable writes on any locations (regions) for geo-replicated database accounts in the Azure Cosmos DB service.
void	setConnectionMode(ConnectionMode connectionMode) Sets the connection mode used in the client.
void	setDirectRequestTimeout(int directRequestTimeout) Sets the direct mode request timeout (time to wait for response from network peer) in seconds This only applies to requests that talk directly to the backend.
void	setEnableEndpointDiscovery(boolean enableEndpointDiscovery) Sets the flag to enable endpoint discovery for geo-replicated database accounts.
void	setHandleServiceUnavailableFromProxy(boolean handleServiceUnavailableFromProxy) Sets the flag to handle service unavailable errors returned without a service version header, by a proxy.
void	setIdleConnectionTimeout(int idleConnectionTimeout) sets the value of the timeout for an idle connection.
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.
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.
void	setProxy(HttpHost proxy) Sets a proxy which will be used when making a request.
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.
void	setUserAgentSuffix(String userAgentSuffix) sets the value of the user-agent suffix.
void	setUsingMultipleWriteLocations(boolean usingMultipleWriteLocations) Sets the flag to enable writes on any locations (regions) for geo-replicated database accounts in the Azure Cosmos DB service.
java.lang.String	toString()

Methods inherited from java.lang.Object

java.lang.Object.clone java.lang.Object.equals java.lang.Object.finalize java.lang.Object.getClass java.lang.Object.hashCode java.lang.Object.notify java.lang.Object.notifyAll java.lang.Object.toString java.lang.Object.wait java.lang.Object.wait java.lang.Object.wait

Constructor Details

ConnectionPolicy

public ConnectionPolicy()

Constructor.

Method Details

GetDefault

public static ConnectionPolicy GetDefault()

Gets the default connection policy.

Returns:

the default connection policy.

getConnectionMode

public ConnectionMode getConnectionMode()

Gets the connection mode used in the client.

Returns:

the connection mode.

getDirectRequestTimeout

public int getDirectRequestTimeout()

Gets the direct mode request timeout (time to wait for response from network peer) in seconds This only applies to requests that talk directly to the backend. Use ConnectionPolicy#getRequestTimeout for requests that go through gateway.

Returns:

the direct request timeout in seconds.

getEnableEndpointDiscovery

public boolean getEnableEndpointDiscovery()

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

Returns:

whether endpoint discovery is enabled.

getHandleServiceUnavailableFromProxy

public boolean getHandleServiceUnavailableFromProxy()

Gets the flag to handle service unavailable errors returned without a service version header, by a proxy. When the value of this property is true, the SDK will handle it as a known error and perform retries. Default value is false as this is an opt in feature.

Returns:

flag to handle service unavailable errors returned without a service version header, by a proxy.

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 null.

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.

isUsingMultipleWriteLocations

public boolean isUsingMultipleWriteLocations()

Gets the flag to enable writes on any locations (regions) for geo-replicated database accounts in the Azure Cosmos DB service. When the value of this property is true, the SDK will direct write operations to available writable locations of geo-replicated database account. Writable locations are ordered by PreferredLocations property. Setting the property value to true has no effect until EnableMultipleWriteLocations in DatabaseAccount is also set to true. Default value is false indicating that writes are only directed to first region in PreferredLocations property.

Returns:

flag to enable writes on any locations (regions) for geo-replicated database accounts.

setConnectionMode

public void setConnectionMode(ConnectionMode connectionMode)

Sets the connection mode used in the client.

Parameters:

connectionMode - the connection mode.

setDirectRequestTimeout

public void setDirectRequestTimeout(int directRequestTimeout)

Sets the direct mode request timeout (time to wait for response from network peer) in seconds This only applies to requests that talk directly to the backend. Use ConnectionPolicy#setRequestTimeout for requests that go through gateway.

Parameters:

directRequestTimeout - the direct request timeout in seconds.

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.

setHandleServiceUnavailableFromProxy

public void setHandleServiceUnavailableFromProxy(boolean handleServiceUnavailableFromProxy)

Sets the flag to handle service unavailable errors returned without a service version header, by a proxy. When the value of this property is true, the SDK will handle it as a known error and perform retries. Default value is false as this is an opt in feature.

Parameters:

handleServiceUnavailableFromProxy - flag to handle service unavailable errors returned without a service version header, by a proxy.

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 null.

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.

setUsingMultipleWriteLocations

public void setUsingMultipleWriteLocations(boolean usingMultipleWriteLocations)

Sets the flag to enable writes on any locations (regions) for geo-replicated database accounts in the Azure Cosmos DB service. When the value of this property is true, the SDK will direct write operations to available writable locations of geo-replicated database account. Writable locations are ordered by PreferredLocations property. Setting the property value to true has no effect until EnableMultipleWriteLocations in DatabaseAccount is also set to true. Default value is false indicating that writes are only directed to first region in PreferredLocations property.

Parameters:

usingMultipleWriteLocations - flag to enable writes on any locations (regions) for geo-replicated database accounts.

toString

public String toString()

Overrides:

ConnectionPolicy.toString()