loadbalancer-experimental: rename LoadBalancerPolicies to LoadBalanci…

…ngPolicies (#2937)

Motivation:

The naming of LoadBalancerPolicies is inconsistent with what it builds
which are `*LoadBalancingPolicyBuilder`s.

Modifications:

- Rename it to `LoadBalancingPolicies`.
- Keep `LoadBalancerPolicies` but deprecated to be removed after 0.42.45.

servicetalk-examples/http/defaultloadbalancer/src/main/java/io/servicetalk/examples/http/defaultloadbalancer/DefaultLoadBalancerClient.java

@@ -22,10 +22,9 @@
 import io.servicetalk.http.api.HttpResponse;
 import io.servicetalk.http.api.SingleAddressHttpClientBuilder;
 import io.servicetalk.http.netty.HttpClients;
-import io.servicetalk.loadbalancer.LoadBalancerPolicies;
+import io.servicetalk.loadbalancer.LoadBalancingPolicies;
 import io.servicetalk.loadbalancer.LoadBalancers;
 import io.servicetalk.loadbalancer.OutlierDetectorConfig;
-import io.servicetalk.loadbalancer.P2CLoadBalancingPolicyBuilder;
 import io.servicetalk.transport.api.HostAndPort;
 
 import java.net.InetSocketAddress;
@@ -61,7 +60,7 @@ private static LoadBalancerFactory<InetSocketAddress, FilterableStreamingHttpLoa
                         // request count to score hosts. The net result is typically a traffic distribution that will
                         // show a preference toward faster hosts while also rapidly adjust to changes in backend
                         // performance.
-                        LoadBalancerPolicies.p2c()
+                        LoadBalancingPolicies.p2c()
                                 // Set the max effort (default: 5). This is the number of times P2C will pick a random
                                 // pair of hosts in search of a healthy host before giving up. When it gives up it will
                                 // either attempt to use one of the hosts regardless of status if `failOpen == true` or

servicetalk-loadbalancer-experimental-provider/src/main/java/io/servicetalk/loadbalancer/experimental/DefaultLoadBalancerProviderConfig.java

@@ -16,7 +16,7 @@
 package io.servicetalk.loadbalancer.experimental;
 
 import io.servicetalk.client.api.LoadBalancedConnection;
-import io.servicetalk.loadbalancer.LoadBalancerPolicies;
+import io.servicetalk.loadbalancer.LoadBalancingPolicies;
 import io.servicetalk.loadbalancer.LoadBalancingPolicy;
 import io.servicetalk.loadbalancer.OutlierDetectorConfig;
 
@@ -122,7 +122,7 @@ private LBPolicy getLBPolicy() {
 
     <U, C extends LoadBalancedConnection> LoadBalancingPolicy<U, C> getLoadBalancingPolicy() {
         return lbPolicy == LBPolicy.P2C ?
-                LoadBalancerPolicies.p2c().build() : LoadBalancerPolicies.roundRobin().build();
+                LoadBalancingPolicies.p2c().build() : LoadBalancingPolicies.roundRobin().build();
     }
 
     boolean enabledForServiceName(String serviceName) {

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/DefaultLoadBalancerBuilder.java

@@ -198,7 +198,7 @@ private static <C extends LoadBalancedConnection> ConnectionPoolStrategyFactory<
 
     private static <ResolvedAddress, C extends LoadBalancedConnection>
     LoadBalancingPolicy<ResolvedAddress, C> defaultLoadBalancingPolicy() {
-        return LoadBalancerPolicies.roundRobin().build();
+        return LoadBalancingPolicies.roundRobin().build();
     }
 
     private static <C extends LoadBalancedConnection> ConnectionPoolStrategyFactory<C>

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/LoadBalancerPolicies.java

@@ -17,7 +17,9 @@
 
 /**
  * A collections of factories for constructing a {@link LoadBalancingPolicy}.
+ * @deprecated use {@link LoadBalancingPolicies}.
  */
+@Deprecated // TODO: remove after 0.42.45 release.
 public final class LoadBalancerPolicies {
 
     private LoadBalancerPolicies() {

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/LoadBalancingPolicies.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright © 2023 Apple Inc. and the ServiceTalk project authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.servicetalk.loadbalancer;
+
+/**
+ * A collections of factories for constructing a {@link LoadBalancingPolicy}.
+ */
+public final class LoadBalancingPolicies {
+
+    private LoadBalancingPolicies() {
+        // no instances.
+    }
+
+    /**
+     * Builder for the round-robin {@link LoadBalancingPolicy}.
+     * Round-robin load balancing is a strategy that maximizes fairness of the request distribution. This comes at the
+     * cost of being unable to bias toward better performing hosts and can only leverage the course grained
+     * healthy/unhealthy status of a host.
+     * @return a builder for the round-robin {@link LoadBalancingPolicy}.
+     */
+    public static RoundRobinLoadBalancingPolicyBuilder roundRobin() {
+        return new RoundRobinLoadBalancingPolicyBuilder();
+    }
+
+    /**
+     * Builder for the power of two choices (P2C) {@link LoadBalancingPolicy}.
+     * Power of Two Choices (P2C) leverages both course grained healthy/unhealthy status of a host plus additional
+     * fine-grained scoring to prioritize hosts that are both healthy and better performing. See the
+     * {@link P2CLoadBalancingPolicy} for more details.
+     * @return a builder for the power of two choices (P2C) {@link LoadBalancingPolicy}.
+     */
+    public static P2CLoadBalancingPolicyBuilder p2c() {
+        return new P2CLoadBalancingPolicyBuilder();
+    }
+}

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/P2CLoadBalancingPolicyBuilder.java

@@ -24,7 +24,7 @@
 
 /**
  * A builder for immutable {@link P2CLoadBalancingPolicy} instances.
- * @see LoadBalancerPolicies#p2c()
+ * @see LoadBalancingPolicies#p2c()
  */
 public final class P2CLoadBalancingPolicyBuilder {
 

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/RoundRobinLoadBalancingPolicyBuilder.java

@@ -19,7 +19,7 @@
 
 /**
  * A builder for immutable {@link RoundRobinLoadBalancingPolicy} instances.
- * @see LoadBalancerPolicies#roundRobin()
+ * @see LoadBalancingPolicies#roundRobin()
  */
 public final class RoundRobinLoadBalancingPolicyBuilder {
 

servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/RoundRobinToDefaultLBMigrationProvider.java

@@ -124,7 +124,7 @@ public LoadBalancerFactory<ResolvedAddress, C> build() {
                     .build();
 
             LoadBalancingPolicy<ResolvedAddress, C> loadBalancingPolicy =
-                    LoadBalancerPolicies.roundRobin()
+                    LoadBalancingPolicies.roundRobin()
                         .failOpen(false)
                         .ignoreWeights(true)
                         .build();

servicetalk-loadbalancer-experimental/src/test/java/io/servicetalk/loadbalancer/DefaultLoadBalancerTest.java

@@ -48,7 +48,7 @@
 class DefaultLoadBalancerTest extends LoadBalancerTestScaffold {
 
     private LoadBalancingPolicy<String, TestLoadBalancedConnection> loadBalancingPolicy =
-            LoadBalancerPolicies.p2c().build();
+            LoadBalancingPolicies.p2c().build();
     @Nullable
     private Supplier<OutlierDetector<String, TestLoadBalancedConnection>> outlierDetectorFactory;
 

servicetalk-loadbalancer-experimental/src/test/java/io/servicetalk/loadbalancer/EagerNewRoundRobinLoadBalancerTest.java

@@ -25,6 +25,6 @@ protected boolean isRoundRobin() {
     @Override
     protected LoadBalancerBuilder<String, TestLoadBalancedConnection> baseLoadBalancerBuilder() {
         return LoadBalancers.<String, TestLoadBalancedConnection>builder(getClass().getSimpleName())
-                .loadBalancingPolicy(LoadBalancerPolicies.roundRobin().build());
+                .loadBalancingPolicy(LoadBalancingPolicies.roundRobin().build());
     }
 }

servicetalk-loadbalancer-experimental/src/test/java/io/servicetalk/loadbalancer/EagerP2CLoadBalancerTest.java

@@ -25,6 +25,6 @@ protected boolean isRoundRobin() {
     @Override
     protected LoadBalancerBuilder<String, TestLoadBalancedConnection> baseLoadBalancerBuilder() {
         return LoadBalancers.<String, TestLoadBalancedConnection>builder(getClass().getSimpleName())
-                .loadBalancingPolicy(LoadBalancerPolicies.p2c().build());
+                .loadBalancingPolicy(LoadBalancingPolicies.p2c().build());
     }
 }

servicetalk-loadbalancer-experimental/src/test/java/io/servicetalk/loadbalancer/LingeringNewRoundRobinLoadBalancerTest.java

@@ -25,6 +25,6 @@ public boolean isRoundRobin() {
     @Override
     protected LoadBalancerBuilder<String, TestLoadBalancedConnection> baseLoadBalancerBuilder() {
         return LoadBalancers.<String, TestLoadBalancedConnection>builder(getClass().getSimpleName())
-                .loadBalancingPolicy(LoadBalancerPolicies.roundRobin().build());
+                .loadBalancingPolicy(LoadBalancingPolicies.roundRobin().build());
     }
 }

servicetalk-loadbalancer-experimental/src/test/java/io/servicetalk/loadbalancer/LingeringP2CLoadBalancerTest.java

@@ -25,6 +25,6 @@ protected boolean isRoundRobin() {
     @Override
     protected LoadBalancerBuilder<String, TestLoadBalancedConnection> baseLoadBalancerBuilder() {
         return LoadBalancers.<String, TestLoadBalancedConnection>builder(getClass().getSimpleName())
-                .loadBalancingPolicy(LoadBalancerPolicies.p2c().build());
+                .loadBalancingPolicy(LoadBalancingPolicies.p2c().build());
     }
 }