SOLR-17382: remove -a and use full name for addlopts --additional-opt…

…ions (#2684)

* move -a and -addlopts to deprecated and use --jvm-opts for long format.
* this option is only called by scripts, its not called by end users, so we don't need deprecation in RunExampleTool

(cherry picked from commit 53c0c3c)

solr/CHANGES.txt

@@ -19,6 +19,8 @@ Improvements
   which may help reduce distributed-search latency in collections with many shards, especially
   when PKI is used between nodes. (Jason Gerlowski)
 
+* SOLR-17382: Deprecate -a and -addlopts in favour of --jvm-opts for passing options into the JVM in bin/solr.   (Eric Pugh, Christos Malliaridis)
+
 Optimizations
 ---------------------
 * SOLR-14985: Solrj CloudSolrClient with Solr URLs had serious performance regressions (since the

solr/bin/solr

@@ -385,7 +385,7 @@ function print_usage() {
     echo ""
   elif [[ "$CMD" == "start" || "$CMD" == "restart" ]]; then
     echo ""
-    echo "Usage: solr $CMD [-f] [-c] [--host host] [-p port] [-d directory] [-z zkHost] [-m memory] [-e example] [-s solr.solr.home] [-t solr.data.home] [-a \"additional-options\"] [-V]"
+    echo "Usage: solr $CMD [-f] [-c] [--host host] [-p port] [-d directory] [-z zkHost] [-m memory] [-e example] [-s solr.solr.home] [-t solr.data.home] [--jvm-opts \"jvm-opts\"] [-V]"
     echo ""
     echo "  -f                    Start Solr in foreground; default starts Solr in the background"
     echo "                          and sends stdout / stderr to solr-PORT-console.log"
@@ -428,9 +428,9 @@ function print_usage() {
     echo "      schemaless:         Schema-less example (schema is inferred from data during indexing)"
     echo "      films:              Example of starting with _default configset and adding explicit fields dynamically"
     echo ""
-    echo "  -a <jvmParams>        Additional parameters to pass to the JVM when starting Solr, such as to setup"
+    echo "  --jvm-opts <jvmParams> Additional parameters to pass to the JVM when starting Solr, such as to setup"
     echo "                          Java debug options. For example, to enable a Java debugger to attach to the Solr JVM"
-    echo "                          you could pass: -a \"-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=18983\""
+    echo "                          you could pass: --jvm-opts \"-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=18983\""
     echo "                          In most cases, you should wrap the additional parameters in double quotes."
     echo ""
     echo "  -j <jettyParams>      Additional parameters to pass to Jetty when starting Solr."
@@ -1415,9 +1415,9 @@ if [ $# -gt 0 ]; then
             PASS_TO_RUN_EXAMPLE+=("-z" "$ZK_HOST")
             shift 2
         ;;
-        -a|--additional-options|-addlopts)
+        -a|--jvm-opts|-addlopts)
             ADDITIONAL_CMD_OPTS="$2"
-            PASS_TO_RUN_EXAMPLE+=("-a" "$ADDITIONAL_CMD_OPTS")
+            PASS_TO_RUN_EXAMPLE+=("--jvm-opts" "$ADDITIONAL_CMD_OPTS")
             shift 2
         ;;
         -j|--jettyconfig|-jettyconfig)

solr/bin/solr.cmd

@@ -361,7 +361,7 @@ goto done
 
 :start_usage
 @echo.
-@echo Usage: solr %SCRIPT_CMD% [-f] [-c] [--host hostname] [-p port] [-d directory] [-z zkHost] [-m memory] [-e example] [-s solr.solr.home] [-t solr.data.home] [-a "additional-options"] [-V]
+@echo Usage: solr %SCRIPT_CMD% [-f] [-c] [--host hostname] [-p port] [-d directory] [-z zkHost] [-m memory] [-e example] [-s solr.solr.home] [-t solr.data.home] [--jvm-opts "jvm-opts"] [-V]
 @echo.
 @echo   -f            Start Solr in foreground; default starts Solr in the background
 @echo                   and sends stdout / stderr to solr-PORT-console.log
@@ -404,9 +404,9 @@ goto done
 @echo       schemaless:     Schema-less example (schema is inferred from data during indexing)
 @echo       films:          Example of starting with _default configset and defining explicit fields dynamically
 @echo.
-@echo   -a opts       Additional parameters to pass to the JVM when starting Solr, such as to setup
+@echo   --jvm-opts opts Additional parameters to pass to the JVM when starting Solr, such as to setup
 @echo                 Java debug options. For example, to enable a Java debugger to attach to the Solr JVM
-@echo                 you could pass: -a "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=18983"
+@echo                 you could pass: --jvm-opts "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=18983"
 @echo                 In most cases, you should wrap the additional parameters in double quotes.
 @echo.
 @echo   -j opts       Additional parameters to pass to Jetty when starting Solr.
@@ -709,7 +709,7 @@ IF "%1"=="-s" goto set_solr_url
 IF "%1"=="--solr-url" goto set_solr_url
 IF "%1"=="-solrUrl" goto set_solr_url
 IF "%1"=="-a" goto set_addl_opts
-IF "%1"=="--additional-options" goto set_addl_opts
+IF "%1"=="--jvm-opts" goto set_addl_opts
 IF "%1"=="-j" goto set_addl_jetty_config
 IF "%1"=="--jettyconfig" goto set_addl_jetty_config
 IF "%1"=="-noprompt" goto set_noprompt

solr/bin/solr.in.sh

@@ -102,7 +102,7 @@
 
 # Anything you add to the SOLR_OPTS variable will be included in the java
 # start command line as-is, in ADDITION to other options. If you specify the
-# -a option on start script, those options will be appended as well. Examples:
+# --jvm-opts option on start script, those options will be appended as well. Examples:
 #SOLR_OPTS="$SOLR_OPTS -Dsolr.autoSoftCommit.maxTime=3000"
 #SOLR_OPTS="$SOLR_OPTS -Dsolr.autoCommit.maxTime=60000"
 
@@ -301,4 +301,4 @@
 
 # Solr internally doesn't use cookies other than for modules such as Kerberos/Hadoop Auth. If you don't need any of those
 # And you don't need them for an external system (such as a load balancer), you can disable the use of a CookieStore with:
-# SOLR_OPTS="$SOLR_OPTS -Dsolr.http.disableCookies=true"
+# SOLR_OPTS="$SOLR_OPTS -Dsolr.http.disableCookies=true"

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

@@ -108,25 +108,25 @@ public List<Option> getOptions() {
                 "Don't prompt for input; accept all defaults when running examples that accept user input.")
             .build(),
         Option.builder("e")
-            .argName("NAME")
+            .longOpt("example")
             .hasArg()
+            .argName("NAME")
             .required(true)
             .desc("Name of the example to launch, one of: cloud, techproducts, schemaless, films.")
-            .longOpt("example")
             .build(),
         Option.builder("s")
             .longOpt("script")
-            .argName("PATH")
             .hasArg()
+            .argName("PATH")
             .required(false)
             .desc("Path to the bin/solr script.")
             .build(),
         Option.builder("d")
-            .argName("DIR")
+            .longOpt("server-dir")
             .hasArg()
+            .argName("DIR")
             .required(true)
             .desc("Path to the Solr server directory.")
-            .longOpt("server-dir")
             .build(),
         Option.builder("f")
             .longOpt("force")
@@ -135,54 +135,54 @@ public List<Option> getOptions() {
             .build(),
         Option.builder()
             .longOpt("example-dir")
-            .argName("DIR")
             .hasArg()
+            .argName("DIR")
             .required(false)
             .desc(
                 "Path to the Solr example directory; if not provided, ${serverDir}/../example is expected to exist.")
             .build(),
         Option.builder()
             .longOpt("url-scheme")
-            .argName("SCHEME")
             .hasArg()
+            .argName("SCHEME")
             .required(false)
             .desc("Solr URL scheme: http or https, defaults to http if not specified.")
             .build(),
         Option.builder("p")
-            .argName("PORT")
+            .longOpt("port")
             .hasArg()
+            .argName("PORT")
             .required(false)
             .desc("Specify the port to start the Solr HTTP listener on; default is 8983.")
-            .longOpt("port")
             .build(),
         Option.builder()
-            .argName("HOSTNAME")
+            .longOpt("host")
             .hasArg()
+            .argName("HOSTNAME")
             .required(false)
             .desc("Specify the hostname for this Solr instance.")
-            .longOpt("host")
             .build(),
         Option.builder("c")
+            .longOpt("cloud")
             .required(false)
             .desc(
                 "Start Solr in SolrCloud mode; if -z not supplied, an embedded ZooKeeper instance is started on Solr port+1000, such as 9983 if Solr is bound to 8983.")
-            .longOpt("cloud")
             .build(),
         Option.builder("m")
-            .argName("MEM")
+            .longOpt("memory")
             .hasArg()
+            .argName("MEM")
             .required(false)
             .desc(
                 "Sets the min (-Xms) and max (-Xmx) heap size for the JVM, such as: -m 4g results in: -Xms4g -Xmx4g; by default, this script sets the heap size to 512m.")
-            .longOpt("memory")
             .build(),
-        Option.builder("a")
-            .argName("OPTS")
+        Option.builder()
+            .longOpt("jvm-opts")
             .hasArg()
+            .argName("OPTS")
             .required(false)
             .desc(
                 "Additional options to be passed to the JVM when starting example Solr server(s).")
-            .longOpt("addlopts")
             .build(),
         SolrCLI.OPTION_ZKHOST,
         SolrCLI.OPTION_ZKHOST_DEPRECATED);
@@ -604,8 +604,9 @@ protected Map<String, Object> startSolr(
     String forceArg = cli.hasOption("force") ? " --force" : "";
     String verboseArg = verbose ? "-V" : "";
 
-    String addlOpts = cli.getOptionValue('a');
-    String addlOptsArg = (addlOpts != null) ? " -a \"" + addlOpts + "\"" : "";
+    String jvmOpts =
+        cli.hasOption("jvm-opts") ? cli.getOptionValue("jvm-opts") : cli.getOptionValue('a');
+    String jvmOptsArg = (jvmOpts != null) ? " --jvm-opts \"" + jvmOpts + "\"" : "";
 
     File cwd = new File(System.getProperty("user.dir"));
     File binDir = (new File(script)).getParentFile();
@@ -634,7 +635,7 @@ protected Map<String, Object> startSolr(
             forceArg,
             verboseArg,
             extraArgs,
-            addlOptsArg);
+            jvmOptsArg);
     startCmd = startCmd.replaceAll("\\s+", " ").trim(); // for pretty printing
 
     echo("\nStarting up Solr on port " + port + " using command:");

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

@@ -605,7 +605,7 @@ private static void printHelp() {
         "  SolrCloud example (start Solr running in SolrCloud mode using localhost:2181 to connect to Zookeeper, with 1g max heap size and remote Java debug options enabled):");
     print("");
     printGreen(
-        "    ./solr start -c -m 1g -z localhost:2181 -a \"-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044\"");
+        "    ./solr start -c -m 1g -z localhost:2181 --jvm-opts \"-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044\"");
     print("");
     print(
         "  Omit '-z localhost:2181' from the above command if you have defined ZK_HOST in solr.in.sh.");

solr/packaging/test/test_ssl.bats

@@ -526,12 +526,14 @@ teardown() {
   # server1 will run on $SOLR_PORT and will use server1.keystore
   export SOLR_SSL_KEY_STORE=$ssl_dir/server1.keystore.p12
   export SOLR_SSL_TRUST_STORE=$ssl_dir/server1.keystore.p12
-  solr start -c -a "-Dsolr.jetty.sslContext.reload.scanInterval=1 -DsocketTimeout=5000"
-  solr assert --started https://localhost:${SOLR_PORT}/solr --timeout 5000
+  solr start -c --jvm-opts "-Dsolr.jetty.sslContext.reload.scanInterval=1 -DsocketTimeout=5000"
+  solr assert --started https://localhost:${SOLR_PORT} --timeout 5000
 
   # server2 will run on $SOLR2_PORT and will use server2.keystore. Initially, this is the same as server1.keystore
   export SOLR_SSL_KEY_STORE=$ssl_dir/server2.keystore.p12
   export SOLR_SSL_TRUST_STORE=$ssl_dir/server2.keystore.p12
+
+  # leaving -a instead of --jvm-opts for back compat testing.
   solr start -c -z localhost:${ZK_PORT} -p ${SOLR2_PORT} -a "-Dsolr.jetty.sslContext.reload.scanInterval=1 -DsocketTimeout=5000"
   solr assert --started https://localhost:${SOLR2_PORT}/solr --timeout 5000
 

solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc

@@ -51,23 +51,23 @@ If no nodes are already running, restart will skip the step to stop and proceed
 The `bin/solr` script provides many options to allow you to customize the server in common ways, such as changing the listening port.
 However, most of the defaults are adequate for most Solr installations, especially when just getting started.
 
-`-a "<jvmParams>"`::
+`--jvm-opts <jvmParams>`::
 +
 [%autowidth,frame=none]
 |===
 |Optional |Default: none
 |===
 +
 Start Solr with additional JVM parameters, such as those starting with `-X`.
-For example setting up Java debugger to attach to the Solr JVM you could pass: `-a "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=18983"`.
+For example setting up Java debugger to attach to the Solr JVM you could pass: `--jvm-opts "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=18983"`.
 In most cases, you should wrap the additional parameters in double quotes.
 +
-If you are passing JVM parameters that begin with `-D`, you can omit the `-a` option.
+If you are passing JVM parameters that begin with `-D`, you can omit the `--jvm-opts` option.
 +
 *Example*:
 +
 [source,bash]
-bin/solr start -a "-Xdebug -Xrunjdwp:transport=dt_socket, server=y,suspend=n,address=1044"
+bin/solr start --jvm-opts "-Xdebug -Xrunjdwp:transport=dt_socket, server=y,suspend=n,address=1044"
 
 `-j "<jettyParams>"`::
 +

solr/solr-ref-guide/modules/deployment-guide/pages/zookeeper-ensemble.adoc

@@ -515,7 +515,7 @@ The section to look for will start:
 ----
 # Anything you add to the SOLR_OPTS variable will be included in the java
 # start command line as-is, in ADDITION to other options. If you specify the
-# -a option on start script, those options will be appended as well. Examples:
+# --jvm-opts option on start script, those options will be appended as well. Examples:
 ----
 
 Add the following line to increase the file size limit to 2MB:
@@ -534,7 +534,7 @@ The section to look for will start:
 ----
 REM Anything you add to the SOLR_OPTS variable will be included in the java
 REM start command line as-is, in ADDITION to other options. If you specify the
-REM -a option on start script, those options will be appended as well. Examples:
+REM --jvm-opts option on start script, those options will be appended as well. Examples:
 ----
 
 Add the following line to increase the file size limit to 2MB: