Rename API for get/setPreferredLocations and get/setUseMultipleWriteL…

…ocations (#10680)

* rename api for get/setPreferredLocations and get/setUseMultipleWriteLocations

* clean

Co-authored-by: Annie Liang <[email protected]>

sdk/cosmos/azure-cosmos-examples/src/main/java/com/azure/cosmos/rx/examples/multimaster/samples/MultiMasterScenario.java

@@ -51,8 +51,8 @@ public MultiMasterScenario() {
 
         for (String region : regions) {
             ConnectionPolicy policy = new ConnectionPolicy();
-            policy.setUsingMultipleWriteLocations(true);
-            policy.setPreferredLocations(Collections.singletonList(region));
+            policy.setUsingMultipleWriteRegions(true);
+            policy.setPreferredRegions(Collections.singletonList(region));
 
             AsyncDocumentClient client =
                     new AsyncDocumentClient.Builder()

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/BridgeInternal.java

@@ -221,11 +221,11 @@ public static boolean isEnableMultipleWriteLocations(DatabaseAccount account) {
     }
 
     public static boolean getUseMultipleWriteLocations(ConnectionPolicy policy) {
-        return policy.isUsingMultipleWriteLocations();
+        return policy.isUsingMultipleWriteRegions();
     }
 
     public static void setUseMultipleWriteLocations(ConnectionPolicy policy, boolean value) {
-        policy.setUsingMultipleWriteLocations(value);
+        policy.setUsingMultipleWriteRegions(value);
     }
 
     public static <E extends CosmosClientException> Uri getRequestUri(CosmosClientException cosmosClientException) {

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/ConnectionPolicy.java

@@ -29,8 +29,8 @@ public final class ConnectionPolicy {
     private String userAgentSuffix;
     private ThrottlingRetryOptions throttlingRetryOptions;
     private boolean endpointDiscoveryEnabled = true;
-    private List<String> preferredLocations;
-    private boolean usingMultipleWriteLocations = true;
+    private List<String> preferredRegions;
+    private boolean usingMultipleWriteRegions = true;
     private InetSocketAddress inetSocketProxyAddress;
     private Boolean readRequestsFallbackEnabled;
 
@@ -222,22 +222,22 @@ public ConnectionPolicy setEndpointDiscoveryEnabled(boolean endpointDiscoveryEna
     }
 
     /**
-     * Gets the flag to enable writes on any locations (regions) for geo-replicated database accounts in the Azure
+     * Gets the flag to enable writes on any regions for geo-replicated database accounts in the Azure
      * Cosmos DB service.
      * <p>
      * 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
+     * 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.
      * <p>
      * DEFAULT value is true indicating that writes are directed to
-     * available writable locations of geo-replicated database account.
+     * available writable regions of geo-replicated database account.
      *
-     * @return flag to enable writes on any locations (regions) for geo-replicated database accounts.
+     * @return flag to enable writes on any regions for geo-replicated database accounts.
      */
-    public boolean isUsingMultipleWriteLocations() {
-        return this.usingMultipleWriteLocations;
+    public boolean isUsingMultipleWriteRegions() {
+        return this.usingMultipleWriteRegions;
     }
 
     /**
@@ -257,24 +257,24 @@ public Boolean isReadRequestsFallbackEnabled() {
     }
 
     /**
-     * Sets the flag to enable writes on any locations (regions) for geo-replicated database accounts in the Azure
+     * Sets the flag to enable writes on any regions for geo-replicated database accounts in the Azure
      * Cosmos DB service.
      * <p>
      * 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
+     * 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.
      * <p>
      * DEFAULT value is false indicating that writes are only directed to
-     * first region in PreferredLocations property.
+     * first region in PreferredRegions property.
      *
-     * @param usingMultipleWriteLocations flag to enable writes on any locations (regions) for geo-replicated
+     * @param usingMultipleWriteRegions flag to enable writes on any regions for geo-replicated
      * database accounts.
      * @return the ConnectionPolicy.
      */
-    public ConnectionPolicy setUsingMultipleWriteLocations(boolean usingMultipleWriteLocations) {
-        this.usingMultipleWriteLocations = usingMultipleWriteLocations;
+    public ConnectionPolicy setUsingMultipleWriteRegions(boolean usingMultipleWriteRegions) {
+        this.usingMultipleWriteRegions = usingMultipleWriteRegions;
         return this;
     }
 
@@ -298,29 +298,29 @@ public ConnectionPolicy setReadRequestsFallbackEnabled(Boolean readRequestsFallb
     }
 
     /**
-     * Gets the preferred locations for geo-replicated database accounts
+     * Gets the preferred regions for geo-replicated database accounts
      *
-     * @return the list of preferred location.
+     * @return the list of preferred region.
      */
-    public List<String> getPreferredLocations() {
-        return this.preferredLocations != null ? preferredLocations : Collections.emptyList();
+    public List<String> getPreferredRegions() {
+        return this.preferredRegions != null ? this.preferredRegions : Collections.emptyList();
     }
 
     /**
-     * Sets the preferred locations for geo-replicated database accounts. For example,
-     * "East US" as the preferred location.
+     * Sets the preferred regions for geo-replicated database accounts. For example,
+     * "East US" as the preferred region.
      * <p>
      * When EnableEndpointDiscovery is true and PreferredRegions is non-empty,
-     * the SDK will prefer to use the locations in the collection in the order
+     * the SDK will prefer to use the regions in the collection in the order
      * they are specified to perform operations.
      * <p>
      * If EnableEndpointDiscovery is set to false, this property is ignored.
      *
-     * @param preferredLocations the list of preferred locations.
+     * @param preferredRegions the list of preferred regions.
      * @return the ConnectionPolicy.
      */
-    public ConnectionPolicy setPreferredLocations(List<String> preferredLocations) {
-        this.preferredLocations = preferredLocations;
+    public ConnectionPolicy setPreferredRegions(List<String> preferredRegions) {
+        this.preferredRegions = preferredRegions;
         return this;
     }
 
@@ -357,8 +357,8 @@ public String toString() {
                    + ", userAgentSuffix='" + userAgentSuffix + '\''
                    + ", retryOptions=" + throttlingRetryOptions
                    + ", enableEndpointDiscovery=" + endpointDiscoveryEnabled
-                   + ", preferredLocations=" + preferredLocations
-                   + ", usingMultipleWriteLocations=" + usingMultipleWriteLocations
+                   + ", preferredRegions=" + preferredRegions
+                   + ", usingMultipleWriteRegions=" + usingMultipleWriteRegions
                    + ", inetSocketProxyAddress=" + inetSocketProxyAddress
                    + '}';
     }

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/GlobalEndpointManager.java

@@ -50,8 +50,8 @@ public GlobalEndpointManager(DatabaseAccountManagerInternal owner, ConnectionPol
         this.backgroundRefreshLocationTimeIntervalInMS = configs.getUnavailableLocationsExpirationTimeInSeconds() * 1000;
         try {
             this.locationCache = new LocationCache(
-                    new ArrayList<>(connectionPolicy.getPreferredLocations() != null ?
-                            connectionPolicy.getPreferredLocations():
+                    new ArrayList<>(connectionPolicy.getPreferredRegions() != null ?
+                            connectionPolicy.getPreferredRegions():
                             Collections.emptyList()
                     ),
                     owner.getServiceEndpoint(),
@@ -138,7 +138,7 @@ public Mono<Void> refreshLocationAsync(DatabaseAccount databaseAccount, boolean
             if (forceRefresh) {
                 Mono<DatabaseAccount> databaseAccountObs = getDatabaseAccountFromAnyLocationsAsync(
                     this.defaultEndpoint,
-                    new ArrayList<>(this.connectionPolicy.getPreferredLocations()),
+                    new ArrayList<>(this.connectionPolicy.getPreferredRegions()),
                     this::getDatabaseAccountAsync);
 
                 return databaseAccountObs.map(dbAccount -> {
@@ -186,7 +186,7 @@ private Mono<Void> refreshLocationPrivateAsync(DatabaseAccount databaseAccount)
 
                     Mono<DatabaseAccount> databaseAccountObs = getDatabaseAccountFromAnyLocationsAsync(
                             this.defaultEndpoint,
-                            new ArrayList<>(this.connectionPolicy.getPreferredLocations()),
+                            new ArrayList<>(this.connectionPolicy.getPreferredRegions()),
                             this::getDatabaseAccountAsync);
 
                     return databaseAccountObs.map(dbAccount -> {
@@ -246,7 +246,7 @@ private Mono<Void> startRefreshLocationTimerAsync(boolean initialization) {
                             }
 
                             logger.debug("startRefreshLocationTimerAsync() - Invoking refresh, I was registered on [{}]", now);
-                            Mono<DatabaseAccount> databaseAccountObs = GlobalEndpointManager.getDatabaseAccountFromAnyLocationsAsync(this.defaultEndpoint, new ArrayList<>(this.connectionPolicy.getPreferredLocations()),
+                            Mono<DatabaseAccount> databaseAccountObs = GlobalEndpointManager.getDatabaseAccountFromAnyLocationsAsync(this.defaultEndpoint, new ArrayList<>(this.connectionPolicy.getPreferredRegions()),
                                     this::getDatabaseAccountAsync);
 
                             return databaseAccountObs.flatMap(dbAccount -> {

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java

@@ -258,7 +258,7 @@ private void initializeGatewayConfigurationReader() {
         // this.globalEndpointManager.init() must have been already called
         // hence asserting it
         assert(databaseAccount != null);
-        this.useMultipleWriteLocations = this.connectionPolicy.isUsingMultipleWriteLocations() && BridgeInternal.isEnableMultipleWriteLocations(databaseAccount);
+        this.useMultipleWriteLocations = this.connectionPolicy.isUsingMultipleWriteRegions() && BridgeInternal.isEnableMultipleWriteLocations(databaseAccount);
 
         // TODO: add support for openAsync
         // https://msdata.visualstudio.com/CosmosDB/_workitems/edit/332589
@@ -3017,7 +3017,7 @@ public Flux<DatabaseAccount> getDatabaseAccountFromEndpoint(URI endpoint) {
                 logger.warn(message);
             }).map(rsp -> rsp.getResource(DatabaseAccount.class))
                     .doOnNext(databaseAccount -> {
-                        this.useMultipleWriteLocations = this.connectionPolicy.isUsingMultipleWriteLocations()
+                        this.useMultipleWriteLocations = this.connectionPolicy.isUsingMultipleWriteRegions()
                                 && BridgeInternal.isEnableMultipleWriteLocations(databaseAccount);
                     });
         });

sdk/cosmos/azure-cosmos/src/test/java/com/azure/cosmos/ConnectionPolicyTest.java

@@ -36,10 +36,10 @@ public Object[][] connectionProtocolModeArgProvider() {
     }
 
     @Test(groups = { "unit" })
-    public void usingMultipleWriteLocations() {
+    public void usingMultipleWriteRegions() {
         ConnectionPolicy policy = new ConnectionPolicy();
-        assertThat(policy.isUsingMultipleWriteLocations()).isEqualTo(true);
-        policy.setUsingMultipleWriteLocations(false);
-        assertThat(policy.isUsingMultipleWriteLocations()).isEqualTo(false);
+        assertThat(policy.isUsingMultipleWriteRegions()).isEqualTo(true);
+        policy.setUsingMultipleWriteRegions(false);
+        assertThat(policy.isUsingMultipleWriteRegions()).isEqualTo(false);
     }
 }

sdk/cosmos/azure-cosmos/src/test/java/com/azure/cosmos/implementation/TestSuiteBase.java

@@ -921,8 +921,8 @@ static protected Builder createGatewayHouseKeepingDocumentClient() {
     static protected Builder createGatewayRxDocumentClient(ConsistencyLevel consistencyLevel, boolean multiMasterEnabled, List<String> preferredLocations) {
         ConnectionPolicy connectionPolicy = new ConnectionPolicy();
         connectionPolicy.setConnectionMode(ConnectionMode.GATEWAY);
-        connectionPolicy.setUsingMultipleWriteLocations(multiMasterEnabled);
-        connectionPolicy.setPreferredLocations(preferredLocations);
+        connectionPolicy.setUsingMultipleWriteRegions(multiMasterEnabled);
+        connectionPolicy.setPreferredRegions(preferredLocations);
         return new Builder().withServiceEndpoint(TestConfigurations.HOST)
                 .withMasterKeyOrResourceToken(TestConfigurations.MASTER_KEY)
                 .withConnectionPolicy(connectionPolicy)
@@ -936,16 +936,16 @@ static protected Builder createGatewayRxDocumentClient() {
     static protected Builder createDirectRxDocumentClient(ConsistencyLevel consistencyLevel,
                                                                               Protocol protocol,
                                                                               boolean multiMasterEnabled,
-                                                                              List<String> preferredLocations) {
+                                                                              List<String> preferredRegions) {
         ConnectionPolicy connectionPolicy = new ConnectionPolicy();
         connectionPolicy.setConnectionMode(ConnectionMode.DIRECT);
 
-        if (preferredLocations != null) {
-            connectionPolicy.setPreferredLocations(preferredLocations);
+        if (preferredRegions != null) {
+            connectionPolicy.setPreferredRegions(preferredRegions);
         }
 
         if (multiMasterEnabled && consistencyLevel == ConsistencyLevel.SESSION) {
-            connectionPolicy.setUsingMultipleWriteLocations(true);
+            connectionPolicy.setUsingMultipleWriteRegions(true);
         }
 
         Configs configs = Mockito.spy(new Configs());

sdk/cosmos/azure-cosmos/src/test/java/com/azure/cosmos/implementation/directconnectivity/GlobalEndPointManagerTest.java

@@ -129,14 +129,14 @@ public void refreshLocationAsyncForConnectivityIssue() throws Exception {
      * switching to different preferredLocation region
      */
     @Test(groups = {"unit"}, timeOut = TIMEOUT)
-    public void refreshLocationAsyncForConnectivityIssueWithPreferredLocation() throws Exception {
+    public void refreshLocationAsyncForConnectivityIssueWithPreferredRegions() throws Exception {
         ConnectionPolicy connectionPolicy = new ConnectionPolicy();
         connectionPolicy.setEndpointDiscoveryEnabled(true);
-        List<String> preferredLocation = new ArrayList<>();
-        preferredLocation.add("East US");
-        preferredLocation.add("East Asia");
-        connectionPolicy.setPreferredLocations(preferredLocation);
-        connectionPolicy.setUsingMultipleWriteLocations(true);
+        List<String> preferredRegions = new ArrayList<>();
+        preferredRegions.add("East US");
+        preferredRegions.add("East Asia");
+        connectionPolicy.setPreferredRegions(preferredRegions);
+        connectionPolicy.setUsingMultipleWriteRegions(true);
         DatabaseAccount databaseAccount = new DatabaseAccount(dbAccountJson1);
         Mockito.when(databaseAccountManagerInternal.getDatabaseAccountFromEndpoint(Matchers.any())).thenReturn(Flux.just(databaseAccount));
         Mockito.when(databaseAccountManagerInternal.getServiceEndpoint()).thenReturn(new URI("https://testaccount.documents.azure.com:443"));
@@ -225,7 +225,7 @@ public void refreshLocationAsyncForWriteForbidden() throws Exception {
     public void backgroundRefreshForMultiMaster() throws Exception {
         ConnectionPolicy connectionPolicy = new ConnectionPolicy();
         connectionPolicy.setEndpointDiscoveryEnabled(true);
-        connectionPolicy.setUsingMultipleWriteLocations(true);
+        connectionPolicy.setUsingMultipleWriteRegions(true);
         DatabaseAccount databaseAccount = new DatabaseAccount(dbAccountJson4);
         Mockito.when(databaseAccountManagerInternal.getDatabaseAccountFromEndpoint(Matchers.any())).thenReturn(Flux.just(databaseAccount));
         Mockito.when(databaseAccountManagerInternal.getServiceEndpoint()).thenReturn(new URI("https://testaccount.documents.azure.com:443"));
@@ -244,7 +244,7 @@ public void backgroundRefreshForMultiMaster() throws Exception {
     public void startRefreshLocationTimerAsync() throws Exception {
         ConnectionPolicy connectionPolicy = new ConnectionPolicy();
         connectionPolicy.setEndpointDiscoveryEnabled(true);
-        connectionPolicy.setUsingMultipleWriteLocations(true);
+        connectionPolicy.setUsingMultipleWriteRegions(true);
         DatabaseAccount databaseAccount = new DatabaseAccount(dbAccountJson1);
         Mockito.when(databaseAccountManagerInternal.getDatabaseAccountFromEndpoint(Matchers.any())).thenReturn(Flux.just(databaseAccount));
         Mockito.when(databaseAccountManagerInternal.getServiceEndpoint()).thenReturn(new URI("https://testaccount.documents.azure.com:443"));
@@ -340,7 +340,7 @@ private void setBackgroundRefreshLocationTimeIntervalInMS(GlobalEndpointManager
     private GlobalEndpointManager getGlobalEndPointManager() throws Exception {
         ConnectionPolicy connectionPolicy = new ConnectionPolicy();
         connectionPolicy.setEndpointDiscoveryEnabled(true);
-        connectionPolicy.setUsingMultipleWriteLocations(true); // currently without this proper, background refresh will not work
+        connectionPolicy.setUsingMultipleWriteRegions(true); // currently without this proper, background refresh will not work
         DatabaseAccount databaseAccount = new DatabaseAccount(dbAccountJson1);
         Mockito.when(databaseAccountManagerInternal.getDatabaseAccountFromEndpoint(Matchers.any())).thenReturn(Flux.just(databaseAccount));
         Mockito.when(databaseAccountManagerInternal.getServiceEndpoint()).thenReturn(new URI("https://testaccount.documents.azure.com:443"));

sdk/cosmos/azure-cosmos/src/test/java/com/azure/cosmos/implementation/routing/LocationCacheTest.java

@@ -154,7 +154,7 @@ private void initialize(
         ConnectionPolicy connectionPolicy = new ConnectionPolicy();
         connectionPolicy.setEndpointDiscoveryEnabled(enableEndpointDiscovery);
         BridgeInternal.setUseMultipleWriteLocations(connectionPolicy, useMultipleWriteLocations);
-        connectionPolicy.setPreferredLocations(this.preferredLocations);
+        connectionPolicy.setPreferredRegions(this.preferredLocations);
 
         this.endpointManager = new GlobalEndpointManager(mockedClient, connectionPolicy, configs);
     }