core: open up LBv2 APIs for early adopters.
diff --git a/core/src/main/java/io/grpc/LoadBalancer2.java b/core/src/main/java/io/grpc/LoadBalancer2.java
index df19775..2230106 100644
--- a/core/src/main/java/io/grpc/LoadBalancer2.java
+++ b/core/src/main/java/io/grpc/LoadBalancer2.java
@@ -43,8 +43,10 @@
* channel a usable subchannel when asked. This is the new interface that will replace {@link
* LoadBalancer}.
*
- * <p><strong>Warning: this is still in developement. Consult gRPC team before starting any related
- * work.</strong>
+ * <p><strong>IMPORTANT NOTICE FOR IMPLEMENTORS: </strong>The name of this class is temporary. It
+ * will be renamed to {@code LoadBalancer} eventually. Make sure you have read through <a
+ * href="https://github.com/grpc/grpc-java/issues/2656" target="_blank">#2656</a> to understand the
+ * transition path.
*
* <h3>Overview</h3>
*
@@ -61,7 +63,7 @@
*
* <p>{@link Helper Helper} is implemented by gRPC library and provided to {@link Factory
* Factory}. It provides functionalities that a {@code LoadBalancer2} implementation would typically
- * need.</li>
+ * need.
*
* <h3>Channel Executor</h3>
*
@@ -109,7 +111,7 @@
* the pattern above. It may be possible to implement in a different way, but that would usually
* result in more complicated threading.
*/
-@Internal
+@ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
@NotThreadSafe
public abstract class LoadBalancer2 {
/**
diff --git a/core/src/main/java/io/grpc/ManagedChannelBuilder.java b/core/src/main/java/io/grpc/ManagedChannelBuilder.java
index 5413156..ecb3086 100644
--- a/core/src/main/java/io/grpc/ManagedChannelBuilder.java
+++ b/core/src/main/java/io/grpc/ManagedChannelBuilder.java
@@ -159,11 +159,30 @@
*
* <p>If this method is not called, the builder will use {@link PickFirstBalancerFactory}
* for the channel.
+ *
+ * <p>This overrides what was set by {@link #loadBalancerFactory(LoadBalancer2.Factory)}.
*/
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
public abstract T loadBalancerFactory(LoadBalancer.Factory loadBalancerFactory);
/**
+ * Provides a custom {@link LoadBalancer2.Factory} for the channel.
+ *
+ * <p>If this method is not called, the builder will use {@link PickFirstBalancerFactory}
+ * for the channel.
+ *
+ * <p>This overrides what was set by {@link #loadBalancerFactory(LoadBalancer.Factory)}.
+ *
+ * <p><strong>IMPORTANT: </strong>Calling this will make the channel to run the LBv2 code path,
+ * which is new and not as well-exercised as the current one. You should use it only if you want
+ * to try out LBv2, or you are migrating your LoadBalancer implementation to LBv2. See
+ * <a href="https://github.com/grpc/grpc-java/issues/2656" target="_blank">#2656</a> for more
+ * information.
+ */
+ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
+ public abstract T loadBalancerFactory(LoadBalancer2.Factory loadBalancerFactory);
+
+ /**
* Set the decompression registry for use in the channel. This is an advanced API call and
* shouldn't be used unless you are using custom message encoding. The default supported
* decompressors are in {@code DecompressorRegistry.getDefaultInstance}.
diff --git a/core/src/main/java/io/grpc/PickFirstBalancerFactory2.java b/core/src/main/java/io/grpc/PickFirstBalancerFactory2.java
index f1b038d..2ef0d44 100644
--- a/core/src/main/java/io/grpc/PickFirstBalancerFactory2.java
+++ b/core/src/main/java/io/grpc/PickFirstBalancerFactory2.java
@@ -39,9 +39,14 @@
import java.util.List;
/**
- * A {@link LoadBalancer} that provides no load balancing mechanism over the
+ * A {@link LoadBalancer2} that provides no load balancing mechanism over the
* addresses from the {@link NameResolver}. The channel's default behavior
* (currently pick-first) is used for all addresses found.
+ *
+ * <p><strong>TECHNICAL PREVIEW: </strong>The name of this class is temporary. It will be renamed to
+ * {@code PickFirstBalancerFactory} during <a href="https://github.com/grpc/grpc-java/issues/2656"
+ * target="_blank">the transition to LBv2</a>. You should use it only if you want to experiment the
+ * LBv2 code path.
*/
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
public final class PickFirstBalancerFactory2 extends LoadBalancer2.Factory {
diff --git a/core/src/main/java/io/grpc/internal/AbstractManagedChannelImplBuilder.java b/core/src/main/java/io/grpc/internal/AbstractManagedChannelImplBuilder.java
index d20819a..3532e34 100644
--- a/core/src/main/java/io/grpc/internal/AbstractManagedChannelImplBuilder.java
+++ b/core/src/main/java/io/grpc/internal/AbstractManagedChannelImplBuilder.java
@@ -206,9 +206,7 @@
return thisT();
}
- /**
- * DO NOT CALL THIS, as its argument type will soon be renamed.
- */
+ @Override
public final T loadBalancerFactory(final LoadBalancer2.Factory loadBalancerFactory) {
Preconditions.checkState(directServerAddress == null,
"directServerAddress is set (%s), which forbids the use of LoadBalancerFactory",
diff --git a/core/src/main/java/io/grpc/util/RoundRobinLoadBalancerFactory2.java b/core/src/main/java/io/grpc/util/RoundRobinLoadBalancerFactory2.java
index 008b193..a3d9e6a 100644
--- a/core/src/main/java/io/grpc/util/RoundRobinLoadBalancerFactory2.java
+++ b/core/src/main/java/io/grpc/util/RoundRobinLoadBalancerFactory2.java
@@ -69,6 +69,11 @@
* addresses from the {@link NameResolver}. The sub-lists received from the name resolver
* are considered to be an {@link EquivalentAddressGroup} and each of these sub-lists is
* what is then balanced across.
+ *
+ * <p><strong>TECHNICAL PREVIEW: </strong>The name of this class is temporary. It will be renamed to
+ * {@code RoundRobinLoadBalancerFactory} during the
+ * <a href="https://github.com/grpc/grpc-java/issues/2656" target="_blank">transition to LBv2</a>.
+ * You should use it only if you want to experiment the LBv2 code path.
*/
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
public class RoundRobinLoadBalancerFactory2 extends LoadBalancer2.Factory {