[tools] improve bkctl help message

tools/all/src/main/java/org/apache/bookkeeper/tools/cli/commands/BookieCommandGroup.java

@@ -18,6 +18,8 @@
  */
 package org.apache.bookkeeper.tools.cli.commands;
 
+import static org.apache.bookkeeper.tools.common.BKCommandCategories.CATEGORY_INFRA_SERVICE;
+
 import org.apache.bookkeeper.tools.cli.BKCtl;
 import org.apache.bookkeeper.tools.cli.commands.bookie.LastMarkCommand;
 import org.apache.bookkeeper.tools.common.BKFlags;
@@ -36,6 +38,7 @@ public class BookieCommandGroup extends CliCommandGroup<BKFlags> {
         .withName(NAME)
         .withDescription(DESC)
         .withParent(BKCtl.NAME)
+        .withCategory(CATEGORY_INFRA_SERVICE)
         .addCommand(new LastMarkCommand())
         .build();
 

tools/all/src/main/java/org/apache/bookkeeper/tools/cli/commands/BookiesCommandGroup.java

@@ -18,6 +18,8 @@
  */
 package org.apache.bookkeeper.tools.cli.commands;
 
+import static org.apache.bookkeeper.tools.common.BKCommandCategories.CATEGORY_INFRA_SERVICE;
+
 import org.apache.bookkeeper.tools.cli.BKCtl;
 import org.apache.bookkeeper.tools.cli.commands.bookies.ListBookiesCommand;
 import org.apache.bookkeeper.tools.common.BKFlags;
@@ -36,6 +38,7 @@ public class BookiesCommandGroup extends CliCommandGroup<BKFlags> {
         .withName(NAME)
         .withDescription(DESC)
         .withParent(BKCtl.NAME)
+        .withCategory(CATEGORY_INFRA_SERVICE)
         .addCommand(new ListBookiesCommand())
         .build();
 

tools/all/src/main/java/org/apache/bookkeeper/tools/cli/commands/LedgerCommandGroup.java

@@ -18,6 +18,8 @@
  */
 package org.apache.bookkeeper.tools.cli.commands;
 
+import static org.apache.bookkeeper.tools.common.BKCommandCategories.CATEGORY_LEDGER_SERVICE;
+
 import org.apache.bookkeeper.tools.cli.BKCtl;
 import org.apache.bookkeeper.tools.cli.commands.client.SimpleTestCommand;
 import org.apache.bookkeeper.tools.common.BKFlags;
@@ -36,6 +38,7 @@ public class LedgerCommandGroup extends CliCommandGroup<BKFlags> {
         .withName(NAME)
         .withDescription(DESC)
         .withParent(BKCtl.NAME)
+        .withCategory(CATEGORY_LEDGER_SERVICE)
         .addCommand(new SimpleTestCommand())
         .build();
 

tools/framework/src/main/java/org/apache/bookkeeper/tools/common/BKCommandCategories.java

@@ -0,0 +1,36 @@
+/*
+ * 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.bookkeeper.tools.common;
+
+/**
+ * Classes to keep a list of command categories.
+ */
+public final class BKCommandCategories {
+
+    // commands that operate cluster and nodes
+    public static final String CATEGORY_INFRA_SERVICE = "Infrastructure commands";
+
+    // commands that operate ledger service
+    public static final String CATEGORY_LEDGER_SERVICE = "Ledger service commands";
+
+    // commands that operate table service
+    public static final String CATEGORY_TABLE_SERVICE = "Table service commands";
+
+}

tools/framework/src/main/java/org/apache/bookkeeper/tools/framework/CliCommand.java

@@ -41,6 +41,11 @@ public void setParent(String parent) {
             .build();
     }
 
+    @Override
+    public String category() {
+        return spec.category();
+    }
+
     @Override
     public String name() {
         return name;

tools/framework/src/main/java/org/apache/bookkeeper/tools/framework/CliSpec.java

@@ -67,10 +67,12 @@ public static class Builder<CliFlagsT extends CliFlags> {
         private PrintStream console = System.out;
         private boolean isCommandGroup = false;
         private String argumentsUsage = "";
+        private String category = "";
 
         private Builder() {}
 
         private Builder(CliSpec<CliFlagsT> spec) {
+            this.category = spec.category;
             this.name = spec.name;
             this.parent = spec.parent;
             this.usage = spec.usage;
@@ -85,6 +87,11 @@ private Builder(CliSpec<CliFlagsT> spec) {
             this.isCommandGroup = spec.isCommandGroup;
         }
 
+        public Builder<CliFlagsT> withCategory(String category) {
+            this.category = category;
+            return this;
+        }
+
         public Builder<CliFlagsT> withName(String name) {
             this.name = name;
             return this;
@@ -142,6 +149,7 @@ public Builder<CliFlagsT> setCommandGroup(boolean enabled) {
 
         public CliSpec<CliFlagsT> build() {
             return new CliSpec<>(
+                category,
                 name,
                 parent,
                 usage,
@@ -158,6 +166,7 @@ public CliSpec<CliFlagsT> build() {
 
     }
 
+    private final String category;
     private final String name;
     private final String parent;
     private final String usage;
@@ -171,7 +180,8 @@ public CliSpec<CliFlagsT> build() {
     // whether the cli spec is for a command group.
     private final boolean isCommandGroup;
 
-    private CliSpec(String name,
+    private CliSpec(String category,
+                    String name,
                     String parent,
                     String usage,
                     String argumentsUsage,
@@ -182,6 +192,7 @@ private CliSpec(String name,
                     Function<CliFlagsT, Boolean> runFunc,
                     PrintStream console,
                     boolean isCommandGroup) {
+        this.category = category;
         this.name = name;
         this.parent = parent;
         this.usage = usage;
@@ -195,6 +206,10 @@ private CliSpec(String name,
         this.isCommandGroup = isCommandGroup;
     }
 
+    public String category() {
+        return category;
+    }
+
     public String name() {
         return name;
     }

tools/framework/src/main/java/org/apache/bookkeeper/tools/framework/Command.java

@@ -32,6 +32,15 @@ default boolean hidden() {
         return false;
     }
 
+    /**
+     * Return category of this command belongs to.
+     *
+     * @return category name
+     */
+    default String category() {
+        return "";
+    }
+
     /**
      * Return command name.
      *

tools/framework/src/main/java/org/apache/bookkeeper/tools/framework/CommandUtils.java

@@ -27,7 +27,9 @@
 import java.util.Comparator;
 import java.util.List;
 import java.util.Map;
+import java.util.TreeMap;
 import java.util.stream.IntStream;
+import org.apache.commons.lang.StringUtils;
 
 /**
  * Utils to process a commander.
@@ -164,27 +166,51 @@ public static void printAvailableCommands(Map<String, Command> commands,
             return;
         }
 
-        printer.println("Commands:");
-        printer.println();
-
         int longestCommandName = commands
             .keySet()
             .stream()
             .mapToInt(name -> name.length())
             .max()
             .orElse(0);
 
+        // group the commands by category
+        Map<String, Map<String, Command>> categorizedCommands = new TreeMap<>();
         for (Map.Entry<String, Command> commandEntry : commands.entrySet()) {
             if ("help".equals(commandEntry.getKey())) {
-                // don't print help message along with available other commands
+                // don't add help message along with other commands
                 continue;
             }
-            printCommand(printer, commandEntry.getKey(), commandEntry.getValue(), longestCommandName);
+            String category = commandEntry.getValue().category();
+            Map<String, Command> subCommands = categorizedCommands.get(category);
+            if (null == subCommands) {
+                subCommands = new TreeMap<>();
+                categorizedCommands.put(category, subCommands);
+            }
+            subCommands.put(commandEntry.getKey(), commandEntry.getValue());
+        }
+
+        // there is only one category, print all of them under `Commands`.
+        if (categorizedCommands.size() <= 1) {
+            printer.println("Commands:");
+            printer.println();
+        }
+
+        for (Map.Entry<String, Map<String, Command>> categoryEntry : categorizedCommands.entrySet()) {
+            String category = categoryEntry.getKey();
+            printCategoryHeader(printer, category);
+            Map<String, Command> subCommands = categoryEntry.getValue();
+            for (Map.Entry<String, Command> commandEntry : subCommands.entrySet()) {
+                printCommand(printer, commandEntry.getKey(), commandEntry.getValue(), longestCommandName);
+            }
+            printer.println();
         }
 
         Command helpCmd = commands.get("help");
         if (null != helpCmd) {
-            printer.println();
+            if (categorizedCommands.size() > 1) {
+                // if commands has been categorized, put help
+                printCategoryHeader(printer, "Other commands");
+            }
             printCommand(printer, "help", helpCmd, longestCommandName);
         }
 
@@ -215,4 +241,19 @@ private static void printCommand(PrintStream printer,
             command.description());
     }
 
+    private static void printCategoryHeader(PrintStream printer,
+                                            String category) {
+        if (StringUtils.isEmpty(category)) {
+            return;
+        }
+
+        printIndent(printer, 0);
+        printDescription(
+            printer,
+            0,
+            0,
+            category + " :");
+        printer.println();
+    }
+
 }

tools/stream/src/main/java/org/apache/bookkeeper/stream/cli/ClusterCommandGroup.java

@@ -17,6 +17,8 @@
  */
 package org.apache.bookkeeper.stream.cli;
 
+import static org.apache.bookkeeper.tools.common.BKCommandCategories.CATEGORY_INFRA_SERVICE;
+
 import org.apache.bookkeeper.stream.cli.commands.cluster.InitClusterCommand;
 import org.apache.bookkeeper.tools.common.BKFlags;
 import org.apache.bookkeeper.tools.framework.CliCommandGroup;
@@ -34,6 +36,7 @@ public class ClusterCommandGroup extends CliCommandGroup<BKFlags> {
         .withName(NAME)
         .withDescription(DESC)
         .withParent("bkctl")
+        .withCategory(CATEGORY_INFRA_SERVICE)
         .addCommand(new InitClusterCommand())
         .build();
 

tools/stream/src/main/java/org/apache/bookkeeper/stream/cli/NamespaceCommandGroup.java

@@ -17,6 +17,8 @@
  */
 package org.apache.bookkeeper.stream.cli;
 
+import static org.apache.bookkeeper.tools.common.BKCommandCategories.CATEGORY_TABLE_SERVICE;
+
 import org.apache.bookkeeper.stream.cli.commands.namespace.CreateNamespaceCommand;
 import org.apache.bookkeeper.stream.cli.commands.namespace.DeleteNamespaceCommand;
 import org.apache.bookkeeper.stream.cli.commands.namespace.GetNamespaceCommand;
@@ -36,6 +38,7 @@ public class NamespaceCommandGroup extends CliCommandGroup<BKFlags> {
         .withName(NAME)
         .withDescription(DESC)
         .withParent("bkctl")
+        .withCategory(CATEGORY_TABLE_SERVICE)
         .addCommand(new CreateNamespaceCommand())
         .addCommand(new GetNamespaceCommand())
         .addCommand(new DeleteNamespaceCommand())

tools/stream/src/main/java/org/apache/bookkeeper/stream/cli/TableAdminCommandGroup.java

@@ -17,6 +17,8 @@
  */
 package org.apache.bookkeeper.stream.cli;
 
+import static org.apache.bookkeeper.tools.common.BKCommandCategories.CATEGORY_TABLE_SERVICE;
+
 import org.apache.bookkeeper.stream.cli.commands.table.CreateTableCommand;
 import org.apache.bookkeeper.stream.cli.commands.table.DeleteTableCommand;
 import org.apache.bookkeeper.stream.cli.commands.table.GetTableCommand;
@@ -36,6 +38,7 @@ public class TableAdminCommandGroup extends CliCommandGroup<BKFlags> {
         .withName(NAME)
         .withDescription(DESC)
         .withParent("bkctl")
+        .withCategory(CATEGORY_TABLE_SERVICE)
         .addCommand(new CreateTableCommand())
         .addCommand(new GetTableCommand())
         .addCommand(new DeleteTableCommand())

tools/stream/src/main/java/org/apache/bookkeeper/stream/cli/TableCommandGroup.java

@@ -17,6 +17,8 @@
  */
 package org.apache.bookkeeper.stream.cli;
 
+import static org.apache.bookkeeper.tools.common.BKCommandCategories.CATEGORY_TABLE_SERVICE;
+
 import org.apache.bookkeeper.stream.cli.commands.table.DelCommand;
 import org.apache.bookkeeper.stream.cli.commands.table.GetCommand;
 import org.apache.bookkeeper.stream.cli.commands.table.IncrementCommand;
@@ -37,6 +39,7 @@ public class TableCommandGroup extends CliCommandGroup<BKFlags> {
         .withName(NAME)
         .withDescription(DESC)
         .withParent("bkctl")
+        .withCategory(CATEGORY_TABLE_SERVICE)
         .addCommand(new PutCommand())
         .addCommand(new GetCommand())
         .addCommand(new IncrementCommand())