CosmosClientBuilder (Azure SDK for Java Reference Documentation)

java.lang.Object
- com.azure.cosmos.CosmosClientBuilder

public class CosmosClientBuilder
extends Object

Helper class to build CosmosAsyncClient CosmosAsyncClient and CosmosClient CosmosClient instances as logical representation of the Azure Cosmos database service.

When building client, endpoint() and key() are mandatory APIs, without these the initialization will fail.

Though consistencyLevel is not mandatory, but we strongly suggest to pay attention to this API when building client. By default, account consistency level is used if none is provided.

By default, direct connection mode is used if none specified.

     Building Cosmos Async Client minimal APIs (without any customized configurations)
 
 CosmosAsyncClient client = new CosmosClientBuilder()
         .endpoint(serviceEndpoint)
         .key(key)
         .buildAsyncClient();

     Building Cosmos Async Client with customizations
 
 CosmosAsyncClient client = new CosmosClientBuilder()
         .endpoint(serviceEndpoint)
         .key(key)
         .directMode(directConnectionConfig, gatewayConnectionConfig)
         .consistencyLevel(ConsistencyLevel.SESSION)
         .connectionSharingAcrossClientsEnabled(true)
         .contentResponseOnWriteEnabled(true)
         .userAgentSuffix("my-application1-client")
         .preferredRegions(Collections.singletonList("West US", "East US"))
         .buildAsyncClient();

     Building Cosmos Sync Client minimal APIs (without any customized configurations)
 
 CosmosClient client = new CosmosClientBuilder()
         .endpoint(serviceEndpoint)
         .key(key)
         .buildClient();

     Building Cosmos Sync Client with customizations
 
 CosmosClient client = new CosmosClientBuilder()
         .endpoint(serviceEndpoint)
         .key(key)
         .directMode(directConnectionConfig, gatewayConnectionConfig)
         .consistencyLevel(ConsistencyLevel.SESSION)
         .connectionSharingAcrossClientsEnabled(true)
         .contentResponseOnWriteEnabled(true)
         .userAgentSuffix("my-application1-client")
         .preferredRegions(Collections.singletonList("West US", "East US"))
         .buildClient();

Constructor Summary

Constructors
Constructor and Description

CosmosClientBuilder()
Instantiates a new Cosmos client builder.

Constructors
Constructor and Description
`CosmosClientBuilder()` Instantiates a new Cosmos client builder.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CosmosAsyncClient`	`buildAsyncClient()` Builds a cosmos async client with the provided properties
`CosmosClient`	`buildClient()` Builds a cosmos sync client with the provided properties
`CosmosClientBuilder`	`clientTelemetryEnabled(boolean clientTelemetryEnabled)` Sets the flag to enable client telemetry which will periodically collect database operations aggregation statistics, system information like cpu/memory and send it to cosmos monitoring service, which will be helpful during debugging.
`CosmosClientBuilder`	`connectionSharingAcrossClientsEnabled(boolean connectionSharingAcrossClientsEnabled)` Enables connections sharing across multiple Cosmos Clients.
`CosmosClientBuilder`	`consistencyLevel(ConsistencyLevel desiredConsistencyLevel)` Sets the `ConsistencyLevel` to be used By default, `ConsistencyLevel.SESSION` consistency will be used.
`CosmosClientBuilder`	`contentResponseOnWriteEnabled(boolean contentResponseOnWriteEnabled)` Sets the boolean to only return the headers and status code in Cosmos DB response in case of Create, Update and Delete operations on CosmosItem.
`CosmosClientBuilder`	`credential(com.azure.core.credential.AzureKeyCredential credential)` Sets the `AzureKeyCredential` to be used
`CosmosClientBuilder`	`credential(com.azure.core.credential.TokenCredential credential)` Sets the `TokenCredential` used to authorize requests sent to the service.
`CosmosClientBuilder`	`directMode()` Sets the default DIRECT connection configuration to be used.
`CosmosClientBuilder`	`directMode(DirectConnectionConfig directConnectionConfig)` Sets the DIRECT connection configuration to be used.
`CosmosClientBuilder`	`directMode(DirectConnectionConfig directConnectionConfig, GatewayConnectionConfig gatewayConnectionConfig)` Sets the DIRECT connection configuration to be used.
`CosmosClientBuilder`	`endpoint(String endpoint)` Sets the Azure Cosmos DB endpoint the SDK will connect to
`CosmosClientBuilder`	`endpointDiscoveryEnabled(boolean endpointDiscoveryEnabled)` Sets the flag to enable endpoint discovery for geo-replicated database accounts.
`CosmosClientBuilder`	`gatewayMode()` Sets the default GATEWAY connection configuration to be used.
`CosmosClientBuilder`	`gatewayMode(GatewayConnectionConfig gatewayConnectionConfig)` Sets the GATEWAY connection configuration to be used.
`CosmosClientBuilder`	`key(String key)` Sets either a master or readonly key used to perform authentication for accessing resource.
`CosmosClientBuilder`	`multipleWriteRegionsEnabled(boolean multipleWriteRegionsEnabled)` Sets the flag to enable writes on any regions for geo-replicated database accounts in the Azure Cosmos DB service.
`CosmosClientBuilder`	`permissions(List<CosmosPermissionProperties> permissions)` Sets the permission list, which contains the resource tokens needed to access resources.
`CosmosClientBuilder`	`preferredRegions(List<String> preferredRegions)` Sets the preferred regions for geo-replicated database accounts.
`CosmosClientBuilder`	`readRequestsFallbackEnabled(boolean readRequestsFallbackEnabled)` Sets whether to allow for reads to go to multiple regions configured on an account of Azure Cosmos DB service.
`CosmosClientBuilder`	`resourceToken(String resourceToken)` Sets a resource token used to perform authentication for accessing resource.
`CosmosClientBuilder`	`sessionCapturingOverrideEnabled(boolean sessionCapturingOverrideEnabled)` Session capturing is enabled by default for `ConsistencyLevel.SESSION`.
`CosmosClientBuilder`	`throttlingRetryOptions(ThrottlingRetryOptions throttlingRetryOptions)` Sets the retry policy options associated with the DocumentClient instance.
`CosmosClientBuilder`	`userAgentSuffix(String userAgentSuffix)` sets the value of the user-agent suffix.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - CosmosClientBuilder
```
public CosmosClientBuilder()
```
    Instantiates a new Cosmos client builder.
- Method Detail
  - sessionCapturingOverrideEnabled
```
public CosmosClientBuilder sessionCapturingOverrideEnabled(boolean sessionCapturingOverrideEnabled)
```
    Session capturing is enabled by default for ConsistencyLevel.SESSION. For other consistency levels, it is not needed, unless if you need occasionally send requests with Session Consistency while the client is not configured in session.
    enabling Session capturing for Session mode has no effect.
    
    Parameters:
    
    sessionCapturingOverrideEnabled - session capturing override
    
    Returns:
    
    current cosmosClientBuilder
  - connectionSharingAcrossClientsEnabled
```
public CosmosClientBuilder connectionSharingAcrossClientsEnabled(boolean connectionSharingAcrossClientsEnabled)
```
    Enables connections sharing across multiple Cosmos Clients. The default is false.
```
 
 CosmosAsyncClient client1 = new CosmosClientBuilder()
         .endpoint(serviceEndpoint1)
         .key(key1)
         .consistencyLevel(ConsistencyLevel.SESSION)
         .connectionSharingAcrossClientsEnabled(true)
         .buildAsyncClient();

 CosmosAsyncClient client2 = new CosmosClientBuilder()
         .endpoint(serviceEndpoint2)
         .key(key2)
         .consistencyLevel(ConsistencyLevel.SESSION)
         .connectionSharingAcrossClientsEnabled(true)
         .buildAsyncClient();

 // when configured this way client1 and client2 will share connections when possible.
 
 
```
    When you have multiple instances of Cosmos Client in the same JVM interacting to multiple Cosmos accounts, enabling this allows connection sharing in Direct mode if possible between instances of Cosmos Client. Please note, when setting this option, the connection configuration (e.g., socket timeout config, idle timeout config) of the first instantiated client will be used for all other client instances.
    Parameters:
    
    connectionSharingAcrossClientsEnabled - connection sharing
    
    Returns:
    
    current cosmosClientBuilder
  - endpoint
```
public CosmosClientBuilder endpoint(String endpoint)
```
    Sets the Azure Cosmos DB endpoint the SDK will connect to
    
    Parameters:
    
    endpoint - the service endpoint
    
    Returns:
    
    current Builder
  - key
```
public CosmosClientBuilder key(String key)
```
    Sets either a master or readonly key used to perform authentication for accessing resource.
    
    Parameters:
    
    key - master or readonly key
    
    Returns:
    
    current Builder.
  - resourceToken
```
public CosmosClientBuilder resourceToken(String resourceToken)
```
    Sets a resource token used to perform authentication for accessing resource.
    
    Parameters:
    
    resourceToken - resourceToken for authentication
    
    Returns:
    
    current Builder.
  - credential
```
public CosmosClientBuilder credential(com.azure.core.credential.TokenCredential credential)
```
    Sets the TokenCredential used to authorize requests sent to the service.
    
    Parameters:
    
    credential - TokenCredential.
    
    Returns:
    
    the updated CosmosClientBuilder
    
    Throws:
    
    NullPointerException - If credential is null.
  - permissions
```
public CosmosClientBuilder permissions(List<CosmosPermissionProperties> permissions)
```
    Sets the permission list, which contains the resource tokens needed to access resources.
    
    Parameters:
    
    permissions - Permission list for authentication.
    
    Returns:
    
    current Builder.
  - consistencyLevel
```
public CosmosClientBuilder consistencyLevel(ConsistencyLevel desiredConsistencyLevel)
```
    Sets the ConsistencyLevel to be used By default, ConsistencyLevel.SESSION consistency will be used.
    
    Parameters:
    
    desiredConsistencyLevel - ConsistencyLevel
    
    Returns:
    
    current Builder
  - credential
```
public CosmosClientBuilder credential(com.azure.core.credential.AzureKeyCredential credential)
```
    Sets the AzureKeyCredential to be used
    
    Parameters:
    
    credential - AzureKeyCredential
    
    Returns:
    
    current cosmosClientBuilder
  - contentResponseOnWriteEnabled
```
public CosmosClientBuilder contentResponseOnWriteEnabled(boolean contentResponseOnWriteEnabled)
```
    Sets the boolean to only return the headers and status code in Cosmos DB response in case of Create, Update and Delete operations on CosmosItem. If set to false (which is by default), service doesn't return payload in the response. It reduces networking and CPU load by not sending the payload back over the network and serializing it on the client. This feature does not impact RU usage for read or write operations. By-default, this is false.
    
    Parameters:
    
    contentResponseOnWriteEnabled - a boolean indicating whether payload will be included in the response or not
    
    Returns:
    
    current cosmosClientBuilder
  - gatewayMode
```
public CosmosClientBuilder gatewayMode()
```
    Sets the default GATEWAY connection configuration to be used.
    
    Returns:
    
    current CosmosClientBuilder
  - gatewayMode
```
public CosmosClientBuilder gatewayMode(GatewayConnectionConfig gatewayConnectionConfig)
```
    Sets the GATEWAY connection configuration to be used.
    
    Parameters:
    
    gatewayConnectionConfig - gateway connection configuration
    
    Returns:
    
    current CosmosClientBuilder
  - directMode
```
public CosmosClientBuilder directMode()
```
    Sets the default DIRECT connection configuration to be used. By default, the builder is initialized with directMode()
    
    Returns:
    
    current CosmosClientBuilder
  - directMode
```
public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig)
```
    Sets the DIRECT connection configuration to be used. By default, the builder is initialized with directMode()
    
    Parameters:
    
    directConnectionConfig - direct connection configuration
    
    Returns:
    
    current CosmosClientBuilder
  - directMode
```
public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig,
                                      GatewayConnectionConfig gatewayConnectionConfig)
```
    Sets the DIRECT connection configuration to be used. gatewayConnectionConfig - represents basic configuration to be used for gateway client. Even in direct connection mode, some of the meta data operations go through gateway client, Setting gateway connection config in this API doesn't affect the connection mode, which will be Direct in this case.
    
    Parameters:
    
    directConnectionConfig - direct connection configuration to be used
    
    gatewayConnectionConfig - gateway connection configuration to be used
    
    Returns:
    
    current CosmosClientBuilder
  - userAgentSuffix
```
public CosmosClientBuilder userAgentSuffix(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.
    
    Returns:
    
    current CosmosClientBuilder
  - throttlingRetryOptions
```
public CosmosClientBuilder throttlingRetryOptions(ThrottlingRetryOptions throttlingRetryOptions)
```
    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:
    
    throttlingRetryOptions - the RetryOptions instance.
    
    Returns:
    
    current CosmosClientBuilder
    
    Throws:
    
    IllegalArgumentException - thrown if an error occurs
  - preferredRegions
```
public CosmosClientBuilder preferredRegions(List<String> preferredRegions)
```
    Sets the preferred regions for geo-replicated database accounts. For example, "East US" as the preferred region.
    When EnableEndpointDiscovery is true and PreferredRegions is non-empty, the SDK will prefer to use the regions in the container in the order they are specified to perform operations.
    If EnableEndpointDiscovery is set to false, this property is ignored.
    
    Parameters:
    
    preferredRegions - the list of preferred regions.
    
    Returns:
    
    current CosmosClientBuilder
  - endpointDiscoveryEnabled
```
public CosmosClientBuilder endpointDiscoveryEnabled(boolean endpointDiscoveryEnabled)
```
    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:
    
    endpointDiscoveryEnabled - true if EndpointDiscovery is enabled.
    
    Returns:
    
    current CosmosClientBuilder
  - multipleWriteRegionsEnabled
```
public CosmosClientBuilder multipleWriteRegionsEnabled(boolean multipleWriteRegionsEnabled)
```
    Sets the flag to enable writes on any 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 regions of geo-replicated database account. Writable regions are ordered by PreferredRegions property. Setting the property value to true has no effect until EnableMultipleWriteRegions in DatabaseAccount is also set to true.
    DEFAULT value is true indicating that writes are directed to available writable regions of geo-replicated database account.
    
    Parameters:
    
    multipleWriteRegionsEnabled - flag to enable writes on any regions for geo-replicated database accounts.
    
    Returns:
    
    current CosmosClientBuilder
  - clientTelemetryEnabled
```
public CosmosClientBuilder clientTelemetryEnabled(boolean clientTelemetryEnabled)
```
    Sets the flag to enable client telemetry which will periodically collect database operations aggregation statistics, system information like cpu/memory and send it to cosmos monitoring service, which will be helpful during debugging.
    DEFAULT value is false indicating this is opt in feature, by default no telemetry collection.
    
    Parameters:
    
    clientTelemetryEnabled - flag to enable client telemetry.
    
    Returns:
    
    current CosmosClientBuilder
  - readRequestsFallbackEnabled
```
public CosmosClientBuilder readRequestsFallbackEnabled(boolean readRequestsFallbackEnabled)
```
    Sets whether to allow for reads to go to multiple regions configured on an account of Azure Cosmos DB service.
    DEFAULT value is true.
    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. CosmosClientBuilder.endpointDiscoveryEnabled is true 2. the Azure Cosmos DB account has more than one region
    
    Parameters:
    
    readRequestsFallbackEnabled - flag to enable reads to go to multiple regions configured on an account of Azure Cosmos DB service.
    
    Returns:
    
    current CosmosClientBuilder
  - buildAsyncClient
```
public CosmosAsyncClient buildAsyncClient()
```
    Builds a cosmos async client with the provided properties
    
    Returns:
    
    CosmosAsyncClient
  - buildClient
```
public CosmosClient buildClient()
```
    Builds a cosmos sync client with the provided properties
    
    Returns:
    
    CosmosClient

Class CosmosClientBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CosmosClientBuilder

Method Detail

sessionCapturingOverrideEnabled

connectionSharingAcrossClientsEnabled

endpoint

key

resourceToken

credential

permissions

consistencyLevel

credential

contentResponseOnWriteEnabled

gatewayMode

gatewayMode

directMode

directMode

directMode

userAgentSuffix

throttlingRetryOptions

preferredRegions

endpointDiscoveryEnabled

multipleWriteRegionsEnabled

clientTelemetryEnabled

readRequestsFallbackEnabled

buildAsyncClient

buildClient