Use a BalancerRequest for handling all of the balance args

Author: bbeaudreault

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

@@ -0,0 +1,118 @@
+/*
+ *
+ * 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;
+
+import org.apache.yetus.audience.InterfaceAudience;
+import org.apache.yetus.audience.InterfaceStability;
+
+/**
+ * Encapsulates options for executing an unscheduled run of the Balancer.
+ */
+@InterfaceAudience.Public
+@InterfaceStability.Evolving
+public class BalanceRequest {
+
+  /**
+   * Dictates how the balancer should be run based on the request
+   */
+  @InterfaceAudience.Private
+  public enum RunMode {
+    /**
+     * Used internally for when the scheduled chore runs the balancer
+     */
+    CHORE,
+    /**
+     * Used when a user requests the balancer to run
+     */
+    REQUEST,
+
+    /**
+     * Used when a user requests the balancer to run, but wants to force it to
+     * run even if it normally wouldn't
+     */
+    FORCED_REQUEST,
+
+    /**
+     * Used when the user wants to run the balancer in dry run mode, where the balancer
+     * attempts to find a balance plan but does not actually execute it.
+     */
+    DRY_RUN;
+  }
+
+  private final RunMode runMode;
+
+  private BalanceRequest(RunMode runMode) {
+    this.runMode = runMode;
+  }
+
+  /**
+   * Creates a BalancerRequest which runs the balancer in execute mode.
+   * In this mode, the balancer will execute all region moves if an improved
+   * plan is found.
+   *
+   * The balancer will not run if the balance switch is disabled or there are
+   * currently regions in transition. You can force the balancer to run
+   * despite regions being in transition by using {@link #forExecutionIgnoringRegionsInTransition()}
+   */
+  public static BalanceRequest forExecution() {
+    return new BalanceRequest(RunMode.REQUEST);
+  }
+
+  /**
+   * Creates a BalancerRequest which runs the balancer in execute mode.
+   * In this mode, the balancer will execute all region moves if an improved
+   * plan is found.
+   *
+   * Forces balancer to run even if regions are currently in transition. This
+   * should be used with caution.
+   */
+  public static BalanceRequest forExecutionIgnoringRegionsInTransition() {
+    return new BalanceRequest(RunMode.FORCED_REQUEST);
+  }
+
+  /**
+   * 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 static BalanceRequest forDryRun() {
+    return new BalanceRequest(RunMode.DRY_RUN);
+  }
+
+
+  /**
+   * For internal use in converting across RPC layer. Use one of {@link #forExecution()},
+   * {@link #forExecutionIgnoringRegionsInTransition()}, or {@link #forDryRun()}.
+   */
+  @InterfaceAudience.Private
+  public static BalanceRequest forRunMode(RunMode runMode) {
+    return new BalanceRequest(runMode);
+  }
+
+  public RunMode getRunMode() {
+    return runMode;
+  }
+}

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

@@ -33,6 +33,7 @@
 import java.util.stream.Collectors;
 import org.apache.hadoop.conf.Configuration;
 import org.apache.hadoop.hbase.Abortable;
+import org.apache.hadoop.hbase.BalanceRequest;
 import org.apache.hadoop.hbase.CacheEvictionStats;
 import org.apache.hadoop.hbase.ClusterMetrics;
 import org.apache.hadoop.hbase.ClusterMetrics.Option;
@@ -1251,16 +1252,19 @@ default boolean balancer() 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.forExecution());
+  }
 
   /**
-   * Invoke the balancer in dry run mode. Will show plan but not actually move any regions.
-   * Can NOT run for various reasons. Check logs.
+   * Invoke the balancer with the given balance request.  The BalanceRequest defines how the
+   * balancer will run. See {@link BalanceRequest} for more details.
    *
-   * @return <code>true</code> if dry run ran, <code>false</code> otherwise.
+   * @param request defines how the balancer should run
+   * @return <code>true</code> if balancer ran, <code>false</code> otherwise.
    * @throws IOException if a remote or network exception occurs
    */
-  boolean dryRunBalance() throws IOException;
+  boolean balance(BalanceRequest request) throws IOException;
 
   /**
    * Invoke the balancer.  Will run the balancer and if regions to move, it will
@@ -1271,7 +1275,7 @@ default boolean balancer() throws IOException {
    * @return <code>true</code> if balancer ran, <code>false</code> otherwise.
    * @throws IOException if a remote or network exception occurs
    * @deprecated Since 2.0.0. Will be removed in 3.0.0.
-   * Use {@link #balance(boolean)} instead.
+   * Use {@link #balance(BalanceRequest)} instead.
    */
   @Deprecated
   default boolean balancer(boolean force) throws IOException {
@@ -1286,8 +1290,13 @@ default boolean balancer(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(force ? BalanceRequest.forExecutionIgnoringRegionsInTransition() : BalanceRequest.forExecution());
+  }
 
   /**
    * Query the current state of the balancer.

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

@@ -33,6 +33,7 @@
 import java.util.function.Function;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
+import org.apache.hadoop.hbase.BalanceRequest;
 import org.apache.hadoop.hbase.CacheEvictionStats;
 import org.apache.hadoop.hbase.ClusterMetrics;
 import org.apache.hadoop.hbase.ClusterMetrics.Option;
@@ -1258,7 +1259,7 @@ default CompletableFuture<Boolean> balancerSwitch(boolean on) {
    *         {@link CompletableFuture}.
    */
   default CompletableFuture<Boolean> balance() {
-    return balance(false);
+    return balance(BalanceRequest.forExecution());
   }
 
   /**
@@ -1268,16 +1269,14 @@ 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.
    */
-  CompletableFuture<Boolean> balance(boolean forcible);
+  default CompletableFuture<Boolean> balance(boolean forcible) {
+    return balance(forcible ? BalanceRequest.forExecutionIgnoringRegionsInTransition() : BalanceRequest.forExecution());
+  }
 
-  /**
-   * Invoke the balancer in dry run mode. Will show plan but not actually move any regions.
-   * Can NOT run for various reasons. Check logs.
-   *
-   * @return <code>true</code> if dry run ran, <code>false</code> otherwise.
-   */
-  CompletableFuture<Boolean> dryRunBalance();
+  CompletableFuture<Boolean> balance(BalanceRequest request);
 
   /**
    * Query the current state of the balancer.

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

@@ -28,6 +28,7 @@
 import java.util.concurrent.ExecutorService;
 import java.util.function.Function;
 import java.util.regex.Pattern;
+import org.apache.hadoop.hbase.BalanceRequest;
 import org.apache.hadoop.hbase.CacheEvictionStats;
 import org.apache.hadoop.hbase.ClusterMetrics;
 import org.apache.hadoop.hbase.ClusterMetrics.Option;
@@ -684,13 +685,8 @@ public CompletableFuture<Boolean> balancerSwitch(boolean on, boolean drainRITs)
   }
 
   @Override
-  public CompletableFuture<Boolean> balance(boolean forcible) {
-    return wrap(rawAdmin.balance(forcible));
-  }
-
-  @Override
-  public CompletableFuture<Boolean> dryRunBalance() {
-    return wrap(rawAdmin.dryRunBalance());
+  public CompletableFuture<Boolean> balance(BalanceRequest request) {
+    return wrap(rawAdmin.balance(request));
   }
 
   @Override

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

@@ -1488,12 +1488,6 @@ public MasterProtos.BalanceResponse balance(RpcController controller,
         return stub.balance(controller, request);
       }
 
-      @Override
-      public MasterProtos.BalanceResponse dryRunBalance(RpcController controller,
-        MasterProtos.BalanceRequest request) throws ServiceException {
-        return stub.dryRunBalance(controller, request);
-      }
-
       @Override
       public MasterProtos.SetBalancerRunningResponse setBalancerRunning(
           RpcController controller, MasterProtos.SetBalancerRunningRequest request)

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

@@ -47,6 +47,7 @@
 import java.util.stream.Stream;
 import org.apache.hadoop.conf.Configuration;
 import org.apache.hadoop.hbase.Abortable;
+import org.apache.hadoop.hbase.BalanceRequest;
 import org.apache.hadoop.hbase.CacheEvictionStats;
 import org.apache.hadoop.hbase.CacheEvictionStatsBuilder;
 import org.apache.hadoop.hbase.ClusterMetrics;
@@ -1476,35 +1477,11 @@ protected Boolean rpcCall() throws Exception {
     });
   }
 
-  @Override
-  public boolean balance() throws IOException {
-    return executeCallable(new MasterCallable<Boolean>(getConnection(), getRpcControllerFactory()) {
-      @Override
-      protected Boolean rpcCall() throws Exception {
-        return master.balance(getRpcController(),
-            RequestConverter.buildBalanceRequest(false)).getBalancerRan();
-      }
-    });
-  }
-
-  @Override
-  public boolean balance(final boolean force) throws IOException {
+  @Override public boolean balance(BalanceRequest request) throws IOException {
     return executeCallable(new MasterCallable<Boolean>(getConnection(), getRpcControllerFactory()) {
-      @Override
-      protected Boolean rpcCall() throws Exception {
-        return master.balance(getRpcController(),
-            RequestConverter.buildBalanceRequest(force)).getBalancerRan();
-      }
-    });
-  }
-
-  @Override
-  public boolean dryRunBalance() throws IOException {
-    return executeCallable(new MasterCallable<Boolean>(getConnection(), getRpcControllerFactory()) {
-      @Override
-      protected Boolean rpcCall() throws Exception {
-        return master.dryRunBalance(getRpcController(),
-          RequestConverter.buildBalanceRequest(false)).getBalancerRan();
+      @Override protected Boolean rpcCall() throws Exception {
+        return master.balance(getRpcController(), RequestConverter.toBalanceRequest(request))
+          .getBalancerRan();
       }
     });
   }

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

@@ -49,6 +49,7 @@
 
 import org.apache.hadoop.conf.Configuration;
 import org.apache.hadoop.hbase.AsyncMetaTableAccessor;
+import org.apache.hadoop.hbase.BalanceRequest;
 import org.apache.hadoop.hbase.CacheEvictionStats;
 import org.apache.hadoop.hbase.CacheEvictionStatsAggregator;
 import org.apache.hadoop.hbase.ClusterMetrics;
@@ -126,14 +127,13 @@
 import org.apache.hadoop.hbase.shaded.protobuf.generated.HBaseProtos.ProcedureDescription;
 import org.apache.hadoop.hbase.shaded.protobuf.generated.HBaseProtos.RegionSpecifier.RegionSpecifierType;
 import org.apache.hadoop.hbase.shaded.protobuf.generated.HBaseProtos.TableSchema;
+import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos;
 import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos.AbortProcedureRequest;
 import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos.AbortProcedureResponse;
 import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos.AddColumnRequest;
 import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos.AddColumnResponse;
 import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos.AssignRegionRequest;
 import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos.AssignRegionResponse;
-import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos.BalanceRequest;
-import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos.BalanceResponse;
 import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos.ClearDeadServersRequest;
 import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos.ClearDeadServersResponse;
 import org.apache.hadoop.hbase.shaded.protobuf.generated.MasterProtos.CreateNamespaceRequest;
@@ -3210,24 +3210,15 @@ public CompletableFuture<Boolean> balancerSwitch(boolean on, boolean drainRITs)
   }
 
   @Override
-  public CompletableFuture<Boolean> balance(boolean forcible) {
+  public CompletableFuture<Boolean> balance(BalanceRequest request) {
     return this
         .<Boolean> newMasterCaller()
         .action(
-          (controller, stub) -> this.<BalanceRequest, BalanceResponse, Boolean> call(controller,
-            stub, RequestConverter.buildBalanceRequest(forcible),
+          (controller, stub) -> this.<MasterProtos.BalanceRequest, MasterProtos.BalanceResponse, Boolean> call(controller,
+            stub, RequestConverter.toBalanceRequest(request),
             (s, c, req, done) -> s.balance(c, req, done), (resp) -> resp.getBalancerRan())).call();
   }
 
-  @Override
-  public CompletableFuture<Boolean> dryRunBalance() {
-    return this
-      .<Boolean> newMasterCaller()
-      .action(
-        (controller, stub) -> this.<BalanceRequest, BalanceResponse, Boolean> call(controller,
-          stub, RequestConverter.buildBalanceRequest(false),
-          (s, c, req, done) -> s.dryRunBalance(c, req, done), (resp) -> resp.getBalancerRan())).call();
-  }
 
   @Override
   public CompletableFuture<Boolean> isBalancerEnabled() {

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

@@ -599,12 +599,6 @@ public BalanceResponse balance(RpcController controller, BalanceRequest request)
     return stub.balance(controller, request);
   }
 
-  @Override
-  public BalanceResponse dryRunBalance(RpcController controller, BalanceRequest request)
-    throws ServiceException {
-    return stub.dryRunBalance(controller, request);
-  }
-
   @Override
   public AssignRegionResponse assignRegion(RpcController controller, AssignRegionRequest request)
       throws ServiceException {