HBASE-26147: Add a dry run mode to the balancer, where moves are calculated but not actually executed

hbase-client/src/main/java/org/apache/hadoop/hbase/client/Admin.java

@@ -831,7 +831,20 @@ default void unassign(byte[] regionName, boolean force) throws IOException {
    * @return <code>true</code> if balancer ran, <code>false</code> otherwise.
    * @throws IOException if a remote or network exception occurs
    */
-  boolean balance() throws IOException;
+  default boolean balance() throws IOException {
+    return balance(BalanceRequest.defaultInstance())
+      .isBalancerRan();
+  }
+
+  /**
+   * Invoke the balancer with the given balance request.  The BalanceRequest defines how the
+   * balancer will run. See {@link BalanceRequest} for more details.
+   *
+   * @param request defines how the balancer should run
+   * @return {@link BalanceResponse} with details about the results of the invocation.
+   * @throws IOException if a remote or network exception occurs
+   */
+  BalanceResponse balance(BalanceRequest request) throws IOException;
 
   /**
    * Invoke the balancer.  Will run the balancer and if regions to move, it will
@@ -841,8 +854,17 @@ default void unassign(byte[] regionName, boolean force) throws IOException {
    * @param force whether we should force balance even if there is region in transition
    * @return <code>true</code> if balancer ran, <code>false</code> otherwise.
    * @throws IOException if a remote or network exception occurs
+   * @deprecated Since 2.5.0. Will be removed in 4.0.0.
+   * Use {@link #balance(BalanceRequest)} instead.
    */
-  boolean balance(boolean force) throws IOException;
+  @Deprecated
+  default boolean balance(boolean force) throws IOException {
+    return balance(
+      BalanceRequest.newBuilder()
+      .setIgnoreRegionsInTransition(force)
+      .build()
+    ).isBalancerRan();
+  }
 
   /**
    * Query the current state of the balancer.
@@ -2494,10 +2516,20 @@ Pair<List<String>, List<TableName>> getConfiguredNamespacesAndTablesInRSGroup(St
   /**
    * Balance regions in the given RegionServer group
    * @param groupName the group name
-   * @return boolean Whether balance ran or not
+   * @return BalanceResponse details about the balancer run
    * @throws IOException if a remote or network exception occurs
    */
-  boolean balanceRSGroup(String groupName) throws IOException;
+  default BalanceResponse balanceRSGroup(String groupName) throws IOException {
+    return balanceRSGroup(groupName, BalanceRequest.defaultInstance());
+  }
+
+  /**
+   * Balance regions in the given RegionServer group, running based on
+   * the given {@link BalanceRequest}.
+   *
+   * @return BalanceResponse details about the balancer run
+   */
+  BalanceResponse balanceRSGroup(String groupName, BalanceRequest request) throws IOException;
 
   /**
    * Rename rsgroup

hbase-client/src/main/java/org/apache/hadoop/hbase/client/AdminOverAsyncAdmin.java

@@ -374,6 +374,11 @@ public boolean balancerSwitch(boolean onOrOff, boolean synchronous) throws IOExc
     return get(admin.balancerSwitch(onOrOff, synchronous));
   }
 
+
+  public BalanceResponse balance(BalanceRequest request) throws IOException {
+    return get(admin.balance(request));
+  }
+
   @Override
   public boolean balance() throws IOException {
     return get(admin.balance());
@@ -1006,8 +1011,8 @@ public void removeRSGroup(String groupName) throws IOException {
   }
 
   @Override
-  public boolean balanceRSGroup(String groupName) throws IOException {
-    return get(admin.balanceRSGroup(groupName));
+  public BalanceResponse balanceRSGroup(String groupName, BalanceRequest request) throws IOException {
+    return get(admin.balanceRSGroup(groupName, request));
   }
 
   @Override

hbase-client/src/main/java/org/apache/hadoop/hbase/client/AsyncAdmin.java

@@ -1287,7 +1287,8 @@ default CompletableFuture<Boolean> balancerSwitch(boolean on) {
    *         {@link CompletableFuture}.
    */
   default CompletableFuture<Boolean> balance() {
-    return balance(false);
+    return balance(BalanceRequest.defaultInstance())
+      .thenApply(BalanceResponse::isBalancerRan);
   }
 
   /**
@@ -1297,8 +1298,25 @@ default CompletableFuture<Boolean> balance() {
    * @param forcible whether we should force balance even if there is region in transition.
    * @return True if balancer ran, false otherwise. The return value will be wrapped by a
    *         {@link CompletableFuture}.
+   * @deprecated Since 2.5.0. Will be removed in 4.0.0.
+   *  Use {@link #balance(BalanceRequest)} instead.
+   */
+  default CompletableFuture<Boolean> balance(boolean forcible) {
+    return balance(
+      BalanceRequest.newBuilder()
+        .setIgnoreRegionsInTransition(forcible)
+        .build()
+    ).thenApply(BalanceResponse::isBalancerRan);
+  }
+
+  /**
+   * Invoke the balancer with the given balance request.  The BalanceRequest defines how the
+   * balancer will run. See {@link BalanceRequest} for more details.
+   *
+   * @param request defines how the balancer should run
+   * @return {@link BalanceResponse} with details about the results of the invocation.
    */
-  CompletableFuture<Boolean> balance(boolean forcible);
+  CompletableFuture<BalanceResponse> balance(BalanceRequest request);
 
   /**
    * Query the current state of the balancer.
@@ -1722,10 +1740,21 @@ default CompletableFuture<List<OnlineLogRecord>> getSlowLogResponses(
   /**
    * Balance regions in the given RegionServer group
    * @param groupName the group name
-   * @return boolean Whether balance ran or not
+   * @return BalanceResponse details about the balancer run
+   * @throws IOException if a remote or network exception occurs
+   */
+  default CompletableFuture<BalanceResponse> balanceRSGroup(String groupName) {
+    return balanceRSGroup(groupName, BalanceRequest.defaultInstance());
+  }
+
+  /**
+   * Balance regions in the given RegionServer group
+   * @param groupName the group name
+   * @param request options to define how the balancer should run
+   * @return BalanceResponse details about the balancer run
    * @throws IOException if a remote or network exception occurs
    */
-  CompletableFuture<Boolean> balanceRSGroup(String groupName);
+  CompletableFuture<BalanceResponse> balanceRSGroup(String groupName, BalanceRequest request);
 
   /**
    * Rename rsgroup

hbase-client/src/main/java/org/apache/hadoop/hbase/client/AsyncHBaseAdmin.java

@@ -694,8 +694,8 @@ public CompletableFuture<Boolean> balancerSwitch(boolean on, boolean drainRITs)
   }
 
   @Override
-  public CompletableFuture<Boolean> balance(boolean forcible) {
-    return wrap(rawAdmin.balance(forcible));
+  public CompletableFuture<BalanceResponse> balance(BalanceRequest request) {
+    return wrap(rawAdmin.balance(request));
   }
 
   @Override
@@ -883,8 +883,8 @@ public CompletableFuture<Void> removeRSGroup(String groupName) {
   }
 
   @Override
-  public CompletableFuture<Boolean> balanceRSGroup(String groupName) {
-    return wrap(rawAdmin.balanceRSGroup(groupName));
+  public CompletableFuture<BalanceResponse> balanceRSGroup(String groupName, BalanceRequest request) {
+    return wrap(rawAdmin.balanceRSGroup(groupName, request));
   }
 
   @Override

hbase-client/src/main/java/org/apache/hadoop/hbase/client/BalanceRequest.java

@@ -0,0 +1,117 @@
+/*
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 org.apache.hadoop.hbase.client;
+
+import org.apache.yetus.audience.InterfaceAudience;
+import org.apache.yetus.audience.InterfaceStability;
+
+/**
+ * Encapsulates options for executing a run of the Balancer.
+ */
+@InterfaceAudience.Public
+@InterfaceStability.Evolving
+public final class BalanceRequest {
+  private static final BalanceRequest DEFAULT = BalanceRequest.newBuilder().build();
+
+  /**
+   * Builder for constructing a {@link BalanceRequest}
+   */
+  @InterfaceAudience.Public
+  @InterfaceStability.Evolving
+  public final static class Builder {
+    private boolean dryRun = false;
+    private boolean ignoreRegionsInTransition = false;
+
+    private Builder() {}
+
+    /**
+     * Creates a BalancerRequest which runs the balancer in dryRun mode.
+     * In this mode, the balancer will try to find a plan but WILL NOT
+     * execute any region moves or call any coprocessors.
+     *
+     * You can run in dryRun mode regardless of whether the balancer switch
+     * is enabled or disabled, but dryRun mode will not run over an existing
+     * request or chore.
+     *
+     * Dry run is useful for testing out new balance configs. See the logs
+     * on the active HMaster for the results of the dry run.
+     */
+    public Builder setDryRun(boolean dryRun) {
+      this.dryRun = dryRun;
+      return this;
+    }
+
+    /**
+     * Creates a BalancerRequest to cause the balancer to run even if there
+     * are regions in transition.
+     *
+     * WARNING: Advanced usage only, this could cause more issues than it fixes.
+     */
+    public Builder setIgnoreRegionsInTransition(boolean ignoreRegionsInTransition) {
+      this.ignoreRegionsInTransition = ignoreRegionsInTransition;
+      return this;
+    }
+
+    /**
+     * Build the {@link BalanceRequest}
+     */
+    public BalanceRequest build() {
+      return new BalanceRequest(dryRun, ignoreRegionsInTransition);
+    }
+  }
+
+  /**
+   * Create a builder to construct a custom {@link BalanceRequest}.
+   */
+  public static Builder newBuilder() {
+    return new Builder();
+  }
+
+  /**
+   * Get a BalanceRequest for a default run of the balancer. The default mode executes
+   * any moves calculated and will not run if regions are already in transition.
+   */
+  public static BalanceRequest defaultInstance() {
+    return DEFAULT;
+  }
+
+  private final boolean dryRun;
+  private final boolean ignoreRegionsInTransition;
+
+  private BalanceRequest(boolean dryRun, boolean ignoreRegionsInTransition) {
+    this.dryRun = dryRun;
+    this.ignoreRegionsInTransition = ignoreRegionsInTransition;
+  }
+
+  /**
+   * Returns true if the balancer should run in dry run mode, otherwise false. In
+   * dry run mode, moves will be calculated but not executed.
+   */
+  public boolean isDryRun() {
+    return dryRun;
+  }
+
+  /**
+   * Returns true if the balancer should execute even if regions are in transition, otherwise
+   * false. This is an advanced usage feature, as it can cause more issues than it fixes.
+   */
+  public boolean isIgnoreRegionsInTransition() {
+    return ignoreRegionsInTransition;
+  }
+}