JAVA-2041: Deprecate cross-DC failover in DCAwareRoundRobinPolicy (ap…

…ache#1165)

changelog/README.md

@@ -12,6 +12,7 @@
 - [bug] JAVA-1612: Include netty-common jar in binary tarball.
 - [improvement] JAVA-2003: Simplify CBUtil internal API to improve performance.
 - [improvement] JAVA-2002: Reimplement TypeCodec.accepts to improve performance.
+- [documentation] JAVA-2041: Deprecate cross-DC failover in DCAwareRoundRobinPolicy.
 
 
 ### 3.6.0

driver-core/src/main/java/com/datastax/driver/core/policies/DCAwareRoundRobinPolicy.java

@@ -342,7 +342,11 @@ public Builder withLocalDc(String localDc) {
      *
      * @param usedHostsPerRemoteDc the number.
      * @return this builder.
+     * @deprecated This functionality will be removed in the next major release of the driver. DC
+     *   failover shouldn't be done in the driver, which does not have the necessary context to know
+     *   what makes sense considering application semantics.
      */
+    @Deprecated
     public Builder withUsedHostsPerRemoteDc(int usedHostsPerRemoteDc) {
       Preconditions.checkArgument(
           usedHostsPerRemoteDc >= 0, "usedHostsPerRemoteDc must be equal or greater than 0");
@@ -363,7 +367,10 @@ public Builder withUsedHostsPerRemoteDc(int usedHostsPerRemoteDc) {
      * you do.
      *
      * @return this builder.
-     */
+     * @deprecated This functionality will be removed in the next major release of the driver. DC
+     *   failover shouldn't be done in the driver, which does not have the necessary context to know
+     *   what makes sense considering application semantics.     */
+    @Deprecated
     public Builder allowRemoteDCsForLocalConsistencyLevel() {
       this.allowRemoteDCsForLocalConsistencyLevel = true;
       return this;

manual/load_balancing/README.md

@@ -101,14 +101,11 @@ Cluster cluster = Cluster.builder()
         .withLoadBalancingPolicy(
                 DCAwareRoundRobinPolicy.builder()
                         .withLocalDc("myLocalDC")
-                        .withUsedHostsPerRemoteDc(2)
-                        .allowRemoteDCsForLocalConsistencyLevel()
                         .build()
         ).build();
 ```
 
-This policy queries nodes of the local data-center in a round-robin fashion; optionally, it can also try a configurable
-number of hosts in remote data centers if all local hosts failed.
+This policy queries nodes of the local data-center in a round-robin fashion.
 
 Call `withLocalDc` to specify the name of your local datacenter. You can also leave it out, and the driver will use the
 datacenter of the first contact point that was reached [at initialization](../#cluster-initialization). However,
@@ -118,21 +115,6 @@ local datacenter. In general, providing the datacenter name explicitly is a safe
 Hosts belonging to the local datacenter are at distance `LOCAL`, and appear first in query plans (in a round-robin
 fashion).
 
-If you call `withUsedHostsPerRemoteDc`, the policy will pick that number of hosts for each remote DC, and add them at
-the end of query plans. To illustrate this, let's assume that the value is 2, there are 3 datacenters and 3 hosts in the
-local datacenter. Query plans would look like this:
-
-* query 1: localHost1, localHost2, localHost3, host1InRemoteDc1, host2InRemoteDc1, host1InRemoteDc2, host2InRemoteDc2
-* query 2: localHost2, localHost3, localHost1, host1InRemoteDc1, host2InRemoteDc1, host1InRemoteDc2, host2InRemoteDc2
-* query 3: localHost3, localHost1, localHost2, host1InRemoteDc1, host2InRemoteDc1, host1InRemoteDc2, host2InRemoteDc2
-
-Hosts selected by this option are at distance `REMOTE`. Note that they always appear in the same order.
-
-Finally, `allowRemoteDCsForLocalConsistencyLevel` controls whether remote hosts included by the previous option are
-included when the consistency level of the query is `LOCAL_ONE` or `LOCAL_QUORUM`. By default, it is off (remote hosts
-are not included for local CLs).
-
-
 ### [TokenAwarePolicy]
 
 ```java