SOLR-17357: Improve SolrCLI tool --help printout (#2545)

solr/core/src/java/org/apache/solr/cli/RunExampleTool.java

@@ -320,10 +320,7 @@ protected void runExample(CommandLine cli, String exampleName) throws Exception
             "--solr-url", solrUrl
           };
       CreateTool createTool = new CreateTool(stdout);
-      int createCode =
-          createTool.runTool(
-              SolrCLI.processCommandLineArgs(
-                  createTool.getName(), createTool.getOptions(), createArgs));
+      int createCode = createTool.runTool(SolrCLI.processCommandLineArgs(createTool, createArgs));
       if (createCode != 0)
         throw new Exception(
             "Failed to create " + collectionName + " using command: " + Arrays.asList(createArgs));
@@ -353,8 +350,7 @@ protected void runExample(CommandLine cli, String exampleName) throws Exception
               exampledocsDir.getAbsolutePath() + "/*.xml"
             };
         PostTool postTool = new PostTool();
-        CommandLine postToolCli =
-            SolrCLI.parseCmdLine(postTool.getName(), args, postTool.getOptions());
+        CommandLine postToolCli = SolrCLI.parseCmdLine(postTool, args);
         postTool.runTool(postToolCli);
 
       } else {
@@ -435,8 +431,7 @@ protected void runExample(CommandLine cli, String exampleName) throws Exception
               filmsJsonFile.getAbsolutePath()
             };
         PostTool postTool = new PostTool();
-        CommandLine postToolCli =
-            SolrCLI.parseCmdLine(postTool.getName(), args, postTool.getOptions());
+        CommandLine postToolCli = SolrCLI.parseCmdLine(postTool, args);
         postTool.runTool(postToolCli);
 
       } catch (Exception ex) {
@@ -875,10 +870,7 @@ protected String createCloudExampleCollection(
         };
 
     CreateTool createTool = new CreateTool(stdout);
-    int createCode =
-        createTool.runTool(
-            SolrCLI.processCommandLineArgs(
-                createTool.getName(), createTool.getOptions(), createArgs));
+    int createCode = createTool.runTool(SolrCLI.processCommandLineArgs(createTool, createArgs));
 
     if (createCode != 0)
       throw new Exception(

solr/core/src/java/org/apache/solr/cli/SolrCLI.java

@@ -205,7 +205,7 @@ public static void main(String[] args) throws Exception {
       CLIO.err(iae.getMessage());
       System.exit(1);
     }
-    CommandLine cli = parseCmdLine(tool.getName(), args, tool.getOptions());
+    CommandLine cli = parseCmdLine(tool, args);
     System.exit(tool.runTool(cli));
   }
 
@@ -214,7 +214,7 @@ public static Tool findTool(String[] args) throws Exception {
     return newTool(toolType);
   }
 
-  public static CommandLine parseCmdLine(String toolName, String[] args, List<Option> toolOptions) {
+  public static CommandLine parseCmdLine(Tool tool, String[] args) {
     // the parser doesn't like -D props
     List<String> toolArgList = new ArrayList<>();
     List<String> dashDList = new ArrayList<>();
@@ -229,7 +229,7 @@ public static CommandLine parseCmdLine(String toolName, String[] args, List<Opti
     String[] toolArgs = toolArgList.toArray(new String[0]);
 
     // process command-line args to configure this application
-    CommandLine cli = processCommandLineArgs(toolName, toolOptions, toolArgs);
+    CommandLine cli = processCommandLineArgs(tool, toolArgs);
 
     List<String> argList = cli.getArgList();
     argList.addAll(dashDList);
@@ -319,20 +319,24 @@ private static Tool newTool(String toolType) throws Exception {
     throw new IllegalArgumentException(toolType + " is not a valid command!");
   }
 
+  /** Returns tool options for given tool, for usage display purposes. Hides deprecated options. */
   public static Options getToolOptions(Tool tool) {
     Options options = new Options();
     options.addOption(OPTION_HELP);
     options.addOption(OPTION_VERBOSE);
     List<Option> toolOpts = tool.getOptions();
     for (Option toolOpt : toolOpts) {
-      options.addOption(toolOpt);
+      if (!toolOpt.isDeprecated()) {
+        options.addOption(toolOpt);
+      }
     }
     return options;
   }
 
   /** Parses the command-line arguments passed by the user. */
-  public static CommandLine processCommandLineArgs(
-      String toolName, List<Option> customOptions, String[] args) {
+  public static CommandLine processCommandLineArgs(Tool tool, String[] args) {
+    List<Option> customOptions = tool.getOptions();
+    String toolName = tool.getName();
     Options options = new Options();
 
     options.addOption(OPTION_HELP);
@@ -359,24 +363,37 @@ public static CommandLine processCommandLineArgs(
         }
       }
       if (!hasHelpArg) {
-        CLIO.err("Failed to parse command-line arguments due to: " + exp.getMessage());
+        CLIO.err("Failed to parse command-line arguments due to: " + exp.getMessage() + "\n");
+        printToolHelp(tool);
         exit(1);
       } else {
-        HelpFormatter formatter = HelpFormatter.builder().setShowDeprecated(true).get();
-        formatter.printHelp(toolName, options);
+        printToolHelp(tool);
         exit(0);
       }
     }
 
     if (cli.hasOption("help")) {
-      HelpFormatter formatter = new HelpFormatter();
-      formatter.printHelp(toolName, options);
+      printToolHelp(tool);
       exit(0);
     }
 
     return cli;
   }
 
+  /** Prints tool help for a given tool */
+  private static void printToolHelp(Tool tool) {
+    HelpFormatter formatter = HelpFormatter.builder().get();
+    formatter.setWidth(120);
+    Options optionsNoDeprecated = new Options();
+    tool.getOptions().stream()
+        .filter(option -> !option.isDeprecated())
+        .forEach(optionsNoDeprecated::addOption);
+    String usageString = tool.getUsage() == null ? "bin/solr " + tool.getName() : tool.getUsage();
+    boolean autoGenerateUsage = tool.getUsage() == null;
+    formatter.printHelp(
+        usageString, tool.getHeader(), optionsNoDeprecated, tool.getFooter(), autoGenerateUsage);
+  }
+
   /** Scans Jar files on the classpath for Tool implementations to activate. */
   private static List<Class<? extends Tool>> findToolClassesInPackage(String packageName) {
     List<Class<? extends Tool>> toolClasses = new ArrayList<>();

solr/core/src/java/org/apache/solr/cli/Tool.java

@@ -25,6 +25,31 @@ public interface Tool {
   /** Defines the interface to a Solr tool that can be run from this command-line app. */
   String getName();
 
+  /**
+   * Provides a Usage string to display in help output. Defaults to auto generating usage string.
+   * Override for custom string
+   *
+   * @return The custom usage string or 'null' to auto generate (default)
+   */
+  default String getUsage() {
+    return null;
+  }
+
+  /**
+   * Optional header to display before the options in help output. Defaults to 'List of options:'
+   */
+  default String getHeader() {
+    return "\nList of options:";
+  }
+
+  /**
+   * Optional footer to display after the options in help output. Defaults to a link to reference
+   * guide
+   */
+  default String getFooter() {
+    return "\nPlease see the Reference Guide for more tools documentation: https://solr.apache.org/guide/solr/latest/deployment-guide/solr-control-script-reference.html";
+  }
+
   List<Option> getOptions();
 
   int runTool(CommandLine cli) throws Exception;

solr/core/src/test/org/apache/solr/cli/AuthToolTest.java

@@ -81,7 +81,7 @@ public void testEnableAuth() throws Exception {
   private int runTool(String[] args) throws Exception {
     Tool tool = findTool(args);
     assertTrue(tool instanceof AuthTool);
-    CommandLine cli = parseCmdLine(tool.getName(), args, tool.getOptions());
+    CommandLine cli = parseCmdLine(tool, args);
     return tool.runTool(cli);
   }
 }

solr/core/src/test/org/apache/solr/cli/CreateToolTest.java

@@ -60,7 +60,7 @@ public void testCreateCollectionWithBasicAuth() throws Exception {
   private int runTool(String[] args) throws Exception {
     Tool tool = findTool(args);
     assertTrue(tool instanceof CreateTool);
-    CommandLine cli = parseCmdLine(tool.getName(), args, tool.getOptions());
+    CommandLine cli = parseCmdLine(tool, args);
     return tool.runTool(cli);
   }
 }

solr/core/src/test/org/apache/solr/cli/DeleteToolTest.java

@@ -97,7 +97,7 @@ public void testFailsToDeleteProtectedCollection() throws Exception {
   private int runTool(String[] args) throws Exception {
     Tool tool = findTool(args);
     assertTrue(tool instanceof DeleteTool);
-    CommandLine cli = parseCmdLine(tool.getName(), args, tool.getOptions());
+    CommandLine cli = parseCmdLine(tool, args);
     return tool.runTool(cli);
   }
 }

solr/core/src/test/org/apache/solr/cli/HealthcheckToolTest.java

@@ -80,7 +80,7 @@ public void testHealthcheckWithSolrRootUrlParameter() throws Exception {
   private int runTool(String[] args) throws Exception {
     Tool tool = findTool(args);
     assertTrue(tool instanceof HealthcheckTool);
-    CommandLine cli = parseCmdLine(tool.getName(), args, tool.getOptions());
+    CommandLine cli = parseCmdLine(tool, args);
     return tool.runTool(cli);
   }
 }

solr/core/src/test/org/apache/solr/cli/PackageToolTest.java

@@ -374,7 +374,7 @@ public static void testForResponseElement(
   }
 
   private void run(PackageTool tool, String[] args) throws Exception {
-    int res = tool.runTool(SolrCLI.processCommandLineArgs(tool.getName(), tool.getOptions(), args));
+    int res = tool.runTool(SolrCLI.processCommandLineArgs(tool, args));
     assertEquals("Non-zero status returned for: " + Arrays.toString(args), 0, res);
   }
 

solr/core/src/test/org/apache/solr/cli/PostToolTest.java

@@ -150,7 +150,7 @@ public void testRunWithCollectionParam() throws Exception {
   private int runTool(String[] args) throws Exception {
     Tool tool = findTool(args);
     assertTrue(tool instanceof PostTool);
-    CommandLine cli = parseCmdLine(tool.getName(), args, tool.getOptions());
+    CommandLine cli = parseCmdLine(tool, args);
     return tool.runTool(cli);
   }