ConnectionPolicy Class

  • Reference
Package:
com.microsoft.azure.cosmosdb
  • java.lang.Object
    • com.microsoft.azure.cosmosdb.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 getIdleConnectionTimeoutInMillis()

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.
MediaReadMode getMediaReadMode()

Gets the attachment content (aka media) download mode.
int getMediaRequestTimeoutInMillis()

Gets or sets time to wait for response from network peer for attachment content (aka media) operations.
List<String> getPreferredLocations()

Gets the preferred locations for geo-replicated database accounts
InetSocketAddress getProxy()

Gets the InetSocketAddress of proxy server.
int getRequestTimeoutInMillis()

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

Gets the retry policy options associated with the DocumentClient instance.
String getUserAgentSuffix()

Gets the value of user-agent suffix.
Boolean isEnableReadRequestsFallback()

Gets whether to allow for reads to go to multiple regions configured on an account of Azure Cosmos DB service.

Default value is null.

If this property is not set, the default is true for all Consistency Levels other than Bounded Staleness, The default is false for Bounded Staleness. 1. enableEndpointDiscovery is true 2. the Azure Cosmos DB account has more than one region
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 directed to first region in PreferredLocations property if it's a write region or the primary account region if no PreferredLocations are specified.

The value should match your account configuration.

During the client lifetime, writes can change regional endpoint in the case of any event described at https://docs.microsoft.com/azure/cosmos-db/troubleshoot-sdk-availability
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 setEnableReadRequestsFallback(Boolean enableReadRequestsFallback)

Sets whether to allow for reads to go to multiple regions configured on an account of Azure Cosmos DB service.

Default value is null.

If this property is not set, the default is true for all Consistency Levels other than Bounded Staleness, The default is false for Bounded Staleness. 1. enableEndpointDiscovery is true 2. the Azure Cosmos DB account has more than one region
void setIdleConnectionTimeoutInMillis(int idleConnectionTimeoutInMillis)

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, the default is 1000.
void setMediaReadMode(MediaReadMode mediaReadMode)

Sets the attachment content (aka media) download mode.
void setMediaRequestTimeoutInMillis(int mediaRequestTimeoutInMillis)

Gets or sets Time to wait for response from network peer for attachment content (aka media) operations.
void setPreferredLocations(List<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(String proxyHost, int proxyPort)

This will create the InetSocketAddress for proxy server, all the requests to cosmoDB will route from this address.

void setRequestTimeoutInMillis(int requestTimeoutInMillis)

Sets the request timeout (time to wait for response from network peer) in milliseconds. The default is 60 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.
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 directed to first region in PreferredLocations property if it's a write region or the primary account region if no PreferredLocations are specified.

The value should match your account configuration.

During the client lifetime, writes can change regional endpoint in the case of any event described at https://docs.microsoft.com/azure/cosmos-db/troubleshoot-sdk-availability
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.

getIdleConnectionTimeoutInMillis

public int getIdleConnectionTimeoutInMillis()

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.

getMediaReadMode

public MediaReadMode getMediaReadMode()

Gets the attachment content (aka media) download mode.

Returns:

the media read mode.

getMediaRequestTimeoutInMillis

public int getMediaRequestTimeoutInMillis()

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

Returns:

the media request timeout in milliseconds.

getPreferredLocations

public List getPreferredLocations()

Gets the preferred locations for geo-replicated database accounts

Returns:

the list of preferred location.

getProxy

public InetSocketAddress getProxy()

Gets the InetSocketAddress of proxy server.

Returns:

the value of proxyHost.

getRequestTimeoutInMillis

public int getRequestTimeoutInMillis()

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

Returns:

the request timeout in milliseconds.

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.

isEnableReadRequestsFallback

public Boolean isEnableReadRequestsFallback()

Gets whether to allow for reads to go to multiple regions configured on an account of Azure Cosmos DB service.

Default value is null.

If this property is not set, the default is true for all Consistency Levels other than Bounded Staleness, The default is false for Bounded Staleness. 1. enableEndpointDiscovery is true 2. the Azure Cosmos DB account has more than one region

Returns:

flag to allow for reads to go to multiple regions configured on an account of Azure Cosmos DB service.

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 directed to first region in PreferredLocations property if it's a write region or the primary account region if no PreferredLocations are specified.

The value should match your account configuration.

During the client lifetime, writes can change regional endpoint in the case of any event described at https://docs.microsoft.com/azure/cosmos-db/troubleshoot-sdk-availability

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.

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.

setEnableReadRequestsFallback

public void setEnableReadRequestsFallback(Boolean enableReadRequestsFallback)

Sets whether to allow for reads to go to multiple regions configured on an account of Azure Cosmos DB service.

Default value is null.

If this property is not set, the default is true for all Consistency Levels other than Bounded Staleness, The default is false for Bounded Staleness. 1. enableEndpointDiscovery is true 2. the Azure Cosmos DB account has more than one region

Parameters:

enableReadRequestsFallback - flag to enable reads to go to multiple regions configured on an account of Azure Cosmos DB service.

setIdleConnectionTimeoutInMillis

public void setIdleConnectionTimeoutInMillis(int idleConnectionTimeoutInMillis)

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

Parameters:

idleConnectionTimeoutInMillis - the timeout for an idle connection in seconds.

setMaxPoolSize

public void setMaxPoolSize(int maxPoolSize)

Sets the value of the connection pool size, the default is 1000.

Parameters:

maxPoolSize - The value of the connection pool size.

setMediaReadMode

public void setMediaReadMode(MediaReadMode mediaReadMode)

Sets the attachment content (aka media) download mode.

Parameters:

mediaReadMode - the media read mode.

setMediaRequestTimeoutInMillis

public void setMediaRequestTimeoutInMillis(int mediaRequestTimeoutInMillis)

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

Parameters:

mediaRequestTimeoutInMillis - the media request timeout in milliseconds.

setPreferredLocations

public void setPreferredLocations(List 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(String proxyHost, int proxyPort)

This will create the InetSocketAddress for proxy server, all the requests to cosmoDB will route from this address.

Parameters:

proxyHost - The proxy server host.
proxyPort - The proxy server port.

setRequestTimeoutInMillis

public void setRequestTimeoutInMillis(int requestTimeoutInMillis)

Sets the request timeout (time to wait for response from network peer) in milliseconds. The default is 60 seconds.

Parameters:

requestTimeoutInMillis - the request timeout in milliseconds.

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 directed to first region in PreferredLocations property if it's a write region or the primary account region if no PreferredLocations are specified.

The value should match your account configuration.

During the client lifetime, writes can change regional endpoint in the case of any event described at https://docs.microsoft.com/azure/cosmos-db/troubleshoot-sdk-availability

Parameters:

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

toString

public String toString()

Applies to