chore: Update ocmments and refactor

Author: lqiu96

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ChannelPool.java

@@ -69,7 +69,7 @@
  * <p>Package-private for internal use.
  */
 class ChannelPool extends ManagedChannel {
-  private static final String CHANNEL_POOL_CONSECUTIVE_RESIZING_WARNING =
+  static final String CHANNEL_POOL_CONSECUTIVE_RESIZING_WARNING =
       "Channel pool is repeatedly resizing. "
           + "Consider adjusting `initialChannelCount` or `maxResizeDelta` to a more reasonable value. "
           + "See https://docs.cloud.google.com/java/docs/troubleshooting to enable logging "
@@ -90,8 +90,8 @@ class ChannelPool extends ManagedChannel {
   private final String authority;
 
   // The number of consecutive resize cycles to wait before logging a warning about repeated
-  // resizing. This is an arbitrary value chosen to detect repeated requests for changes
-  // (multiple continuous increase or decrease attempts) without being too sensitive.
+  // resizing. This value was chosen to detect repeated requests for changes (multiple continuous
+  // increase or decrease attempts) without being too sensitive.
   private static final int CONSECUTIVE_RESIZE_THRESHOLD = 5;
 
   // Tracks the number of consecutive resize cycles where a resize actually occurred (either expand
@@ -290,7 +290,8 @@ private void resizeSafely() {
    *   <li>Get the maximum number of outstanding RPCs since last invocation
    *   <li>Determine a valid range of number of channels to handle that many outstanding RPCs
    *   <li>If the current number of channel falls outside of that range, add or remove at most
-   *       {@link ChannelPoolSettings#MAX_RESIZE_DELTA} to get closer to middle of that range.
+   *       {@link ChannelPoolSettings#DEFAULT_MAX_RESIZE_DELTA} to get closer to middle of that
+   *       range.
    * </ul>
    *
    * <p>Not threadsafe, must be called under the entryWriteLock monitor
@@ -332,18 +333,19 @@ void resize() {
       dampenedTarget = currentSize + (int) Math.copySign(settings.getMaxResizeDelta(), delta);
     }
 
-    // We only count as "resized" if the thresholds are crossed and we actually attempt to scale.
-    // Checking (dampenedTarget != currentSize) would cause false positives when the pool is within
-    // bounds but not at the target, because the target aims for the middle of the bounds.
+    // Only count as "resized" if the thresholds are crossed and Gax attempts to scale. Checking
+    // that `dampenedTarget != currentSize` would cause false positives when the pool is within
+    // bounds but not at the target (target aims for the middle of the bounds)
     boolean resized = (currentSize < minChannels || currentSize > maxChannels);
     if (resized) {
       consecutiveResizes++;
     } else {
       consecutiveResizes = 0;
     }
 
-    // Log warning only once when the threshold is reached to avoid spamming logs.
-    // Using == instead of >= ensures we don't log on every subsequent resize cycle.
+    // Log warning only once when the consecutive threshold is reached to avoid spamming logs. Log
+    // message will repeat if the number of consecutive resizes resets (e.g. stabilizes for a bit).
+    // However, aim to log once to ensure that this does not incur log spam.
     if (consecutiveResizes == CONSECUTIVE_RESIZE_THRESHOLD) {
       LOG.warning(CHANNEL_POOL_CONSECUTIVE_RESIZING_WARNING);
     }

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ChannelPoolSettings.java

@@ -59,7 +59,7 @@ public abstract class ChannelPoolSettings {
   static final Duration RESIZE_INTERVAL = Duration.ofMinutes(1);
 
   /** The maximum number of channels that can be added or removed at a time. */
-  static final int MAX_RESIZE_DELTA = 2;
+  static final int DEFAULT_MAX_RESIZE_DELTA = 2;
 
   /**
    * Threshold to start scaling down the channel pool.
@@ -96,8 +96,8 @@ public abstract class ChannelPoolSettings {
    * The maximum number of channels that can be added or removed at a time.
    *
    * <p>This setting limits the rate at which the channel pool can grow or shrink in a single resize
-   * period. The default value is {@value #MAX_RESIZE_DELTA}. Increasing this value can help the
-   * pool better handle sudden bursts or spikes in requests by allowing it to scale up faster.
+   * period. The default value is {@value #DEFAULT_MAX_RESIZE_DELTA}. Increasing this value can help
+   * the pool better handle sudden bursts or spikes in requests by allowing it to scale up faster.
    * Regardless of this setting, the number of channels will never exceed {@link
    * #getMaxChannelCount()}.
    */
@@ -127,11 +127,7 @@ boolean isStaticSize() {
       return true;
     }
     // When the scaling threshold are not set
-    if (getMinRpcsPerChannel() == 0 && getMaxRpcsPerChannel() == Integer.MAX_VALUE) {
-      return true;
-    }
-
-    return false;
+    return getMinRpcsPerChannel() == 0 && getMaxRpcsPerChannel() == Integer.MAX_VALUE;
   }
 
   public abstract Builder toBuilder();
@@ -143,7 +139,6 @@ public static ChannelPoolSettings staticallySized(int size) {
         .setMaxRpcsPerChannel(Integer.MAX_VALUE)
         .setMinChannelCount(size)
         .setMaxChannelCount(size)
-        .setMaxResizeDelta(Math.min(MAX_RESIZE_DELTA, size))
         .build();
   }
 
@@ -155,7 +150,7 @@ public static Builder builder() {
         .setMinRpcsPerChannel(0)
         .setMaxRpcsPerChannel(Integer.MAX_VALUE)
         .setPreemptiveRefreshEnabled(false)
-        .setMaxResizeDelta(MAX_RESIZE_DELTA);
+        .setMaxResizeDelta(DEFAULT_MAX_RESIZE_DELTA);
   }
 
   @AutoValue.Builder

sdk-platform-java/gax-java/gax-grpc/src/test/java/com/google/api/gax/grpc/ChannelPoolTest.java

@@ -784,9 +784,7 @@ void repeatedResizingLogsWarningOnExpand() throws Exception {
       pool.resize();
       assertThat(logHandler.getAllMessages()).hasSize(1);
       assertThat(logHandler.getAllMessages())
-          .contains(
-              "Channel pool is repeatedly resizing. Consider adjusting `initialChannelCount` or `maxResizeDelta` to a more reasonable value. "
-                  + "See https://docs.cloud.google.com/java/docs/troubleshooting to enable logging and set `com.google.api.gax.grpc.ChannelPool.level=FINEST` to log the channel pool resize behavior.");
+          .contains(ChannelPool.CHANNEL_POOL_CONSECUTIVE_RESIZING_WARNING);
 
       // 6th resize, should not log again
       pool.resize();
@@ -837,9 +835,7 @@ void repeatedResizingLogsWarningOnShrink() throws Exception {
       // 5th resize, should log warning
       pool.resize();
       assertThat(logHandler.getAllMessages())
-          .contains(
-              "Channel pool is repeatedly resizing. Consider adjusting `initialChannelCount` or `maxResizeDelta` to a more reasonable value. "
-                  + "See https://docs.cloud.google.com/java/docs/troubleshooting to enable logging and set `com.google.api.gax.grpc.ChannelPool.level=FINEST` to log the channel pool resize behavior.");
+          .contains(ChannelPool.CHANNEL_POOL_CONSECUTIVE_RESIZING_WARNING);
     } finally {
       ChannelPool.LOG.removeHandler(logHandler);
     }