Rename UserError

The top-level class Throwable represents all errors and exceptions in
Java. This hierarchy is divided into Error and Exception, the former
being serious problems that applications should not try to catch and the
latter representing exceptional conditions that an application might
want to catch and handle. This commit renames
org.elasticsearch.cli.UserError to org.elasticsearch.UserException to
make its name consistent with where it falls in this hierarchy.

Relates #19254

Author: jasontedor

core/src/main/java/org/elasticsearch/bootstrap/Elasticsearch.java

@@ -25,7 +25,7 @@
 import org.elasticsearch.cli.ExitCodes;
 import org.elasticsearch.cli.SettingCommand;
 import org.elasticsearch.cli.Terminal;
-import org.elasticsearch.cli.UserError;
+import org.elasticsearch.cli.UserException;
 import org.elasticsearch.monitor.jvm.JvmInfo;
 
 import java.io.IOException;
@@ -73,11 +73,11 @@ static int main(final String[] args, final Elasticsearch elasticsearch, final Te
     @Override
     protected void execute(Terminal terminal, OptionSet options, Map<String, String> settings) throws Exception {
         if (options.nonOptionArguments().isEmpty() == false) {
-            throw new UserError(ExitCodes.USAGE, "Positional arguments not allowed, found " + options.nonOptionArguments());
+            throw new UserException(ExitCodes.USAGE, "Positional arguments not allowed, found " + options.nonOptionArguments());
         }
         if (options.has(versionOption)) {
             if (options.has(daemonizeOption) || options.has(pidfileOption)) {
-                throw new UserError(ExitCodes.USAGE, "Elasticsearch version option is mutually exclusive with any other option");
+                throw new UserException(ExitCodes.USAGE, "Elasticsearch version option is mutually exclusive with any other option");
             }
             terminal.println("Version: " + org.elasticsearch.Version.CURRENT
                     + ", Build: " + Build.CURRENT.shortHash() + "/" + Build.CURRENT.date()

core/src/main/java/org/elasticsearch/cli/Command.java

@@ -55,7 +55,7 @@ public final int main(String[] args, Terminal terminal) throws Exception {
             printHelp(terminal);
             terminal.println(Terminal.Verbosity.SILENT, "ERROR: " + e.getMessage());
             return ExitCodes.USAGE;
-        } catch (UserError e) {
+        } catch (UserException e) {
             if (e.exitCode == ExitCodes.USAGE) {
                 printHelp(terminal);
             }
@@ -79,7 +79,7 @@ void mainWithoutErrorHandling(String[] args, Terminal terminal) throws Exception
         if (options.has(silentOption)) {
             if (options.has(verboseOption)) {
                 // mutually exclusive, we can remove this with jopt-simple 5.0, which natively supports it
-                throw new UserError(ExitCodes.USAGE, "Cannot specify -s and -v together");
+                throw new UserException(ExitCodes.USAGE, "Cannot specify -s and -v together");
             }
             terminal.setVerbosity(Terminal.Verbosity.SILENT);
         } else if (options.has(verboseOption)) {
@@ -110,7 +110,7 @@ protected static void exit(int status) {
     /**
      * Executes this command.
      *
-     * Any runtime user errors (like an input file that does not exist), should throw a {@link UserError}. */
+     * Any runtime user errors (like an input file that does not exist), should throw a {@link UserException}. */
     protected abstract void execute(Terminal terminal, OptionSet options) throws Exception;
 
 }

core/src/main/java/org/elasticsearch/cli/MultiCommand.java

@@ -60,11 +60,11 @@ protected void execute(Terminal terminal, OptionSet options) throws Exception {
         }
         String[] args = arguments.values(options).toArray(new String[0]);
         if (args.length == 0) {
-            throw new UserError(ExitCodes.USAGE, "Missing command");
+            throw new UserException(ExitCodes.USAGE, "Missing command");
         }
         Command subcommand = subcommands.get(args[0]);
         if (subcommand == null) {
-            throw new UserError(ExitCodes.USAGE, "Unknown command [" + args[0] + "]");
+            throw new UserException(ExitCodes.USAGE, "Unknown command [" + args[0] + "]");
         }
         subcommand.mainWithoutErrorHandling(Arrays.copyOfRange(args, 1, args.length), terminal);
     }

core/src/main/java/org/elasticsearch/cli/SettingCommand.java

@@ -41,7 +41,7 @@ protected void execute(Terminal terminal, OptionSet options) throws Exception {
         final Map<String, String> settings = new HashMap<>();
         for (final KeyValuePair kvp : settingOption.values(options)) {
             if (kvp.value.isEmpty()) {
-                throw new UserError(ExitCodes.USAGE, "Setting [" + kvp.key + "] must not be empty");
+                throw new UserException(ExitCodes.USAGE, "Setting [" + kvp.key + "] must not be empty");
             }
             settings.put(kvp.key, kvp.value);
         }

core/src/main/java/org/elasticsearch/cli/UserError.java renamed to core/src/main/java/org/elasticsearch/cli/UserException.java

@@ -22,13 +22,13 @@
 /**
  * An exception representing a user fixable problem in {@link Command} usage.
  */
-public class UserError extends Exception {
+public class UserException extends Exception {
 
     /** The exist status the cli should use when catching this user error. */
     public final int exitCode;
 
-    /** Constructs a UserError with an exit status and message to show the user. */
-    public UserError(int exitCode, String msg) {
+    /** Constructs a UserException with an exit status and message to show the user. */
+    public UserException(int exitCode, String msg) {
         super(msg);
         this.exitCode = exitCode;
     }

core/src/main/java/org/elasticsearch/plugins/InstallPluginCommand.java

@@ -29,7 +29,7 @@
 import org.elasticsearch.cli.ExitCodes;
 import org.elasticsearch.cli.SettingCommand;
 import org.elasticsearch.cli.Terminal;
-import org.elasticsearch.cli.UserError;
+import org.elasticsearch.cli.UserException;
 import org.elasticsearch.common.collect.Tuple;
 import org.elasticsearch.common.hash.MessageDigests;
 import org.elasticsearch.common.io.FileSystemUtils;
@@ -188,7 +188,7 @@ protected void execute(Terminal terminal, OptionSet options, Map<String, String>
         // TODO: in jopt-simple 5.0 we can enforce a min/max number of positional args
         List<String> args = arguments.values(options);
         if (args.size() != 1) {
-            throw new UserError(ExitCodes.USAGE, "Must supply a single plugin id argument");
+            throw new UserException(ExitCodes.USAGE, "Must supply a single plugin id argument");
         }
         String pluginId = args.get(0);
         boolean isBatch = options.has(batchOption) || System.console() == null;
@@ -250,7 +250,7 @@ private Path download(Terminal terminal, String pluginId, Path tmpDir) throws Ex
             if (plugins.isEmpty() == false) {
                 msg += ", did you mean " + (plugins.size() == 1 ? "[" + plugins.get(0) + "]": "any of " + plugins.toString()) + "?";
             }
-            throw new UserError(ExitCodes.USAGE, msg);
+            throw new UserException(ExitCodes.USAGE, msg);
         }
         terminal.println("-> Downloading " + URLDecoder.decode(pluginId, "UTF-8"));
         return downloadZip(terminal, pluginId, tmpDir);
@@ -328,20 +328,20 @@ private Path downloadZipAndChecksum(Terminal terminal, String urlString, Path tm
             BufferedReader checksumReader = new BufferedReader(new InputStreamReader(in, StandardCharsets.UTF_8));
             expectedChecksum = checksumReader.readLine();
             if (checksumReader.readLine() != null) {
-                throw new UserError(ExitCodes.IO_ERROR, "Invalid checksum file at " + checksumUrl);
+                throw new UserException(ExitCodes.IO_ERROR, "Invalid checksum file at " + checksumUrl);
             }
         }
 
         byte[] zipbytes = Files.readAllBytes(zip);
         String gotChecksum = MessageDigests.toHexString(MessageDigests.sha1().digest(zipbytes));
         if (expectedChecksum.equals(gotChecksum) == false) {
-            throw new UserError(ExitCodes.IO_ERROR, "SHA1 mismatch, expected " + expectedChecksum + " but got " + gotChecksum);
+            throw new UserException(ExitCodes.IO_ERROR, "SHA1 mismatch, expected " + expectedChecksum + " but got " + gotChecksum);
         }
 
         return zip;
     }
 
-    private Path unzip(Path zip, Path pluginsDir) throws IOException, UserError {
+    private Path unzip(Path zip, Path pluginsDir) throws IOException, UserException {
         // unzip plugin to a staging temp dir
 
         final Path target = stagingDirectory(pluginsDir);
@@ -386,7 +386,7 @@ private Path unzip(Path zip, Path pluginsDir) throws IOException, UserError {
         Files.delete(zip);
         if (hasEsDir == false) {
             IOUtils.rm(target);
-            throw new UserError(ExitCodes.DATA_ERROR, "`elasticsearch` directory is missing in the plugin zip");
+            throw new UserException(ExitCodes.DATA_ERROR, "`elasticsearch` directory is missing in the plugin zip");
         }
         return target;
     }
@@ -425,7 +425,7 @@ private PluginInfo verify(Terminal terminal, Path pluginRoot, boolean isBatch, E
         // don't let luser install plugin as a module...
         // they might be unavoidably in maven central and are packaged up the same way)
         if (MODULES.contains(info.getName())) {
-            throw new UserError(ExitCodes.USAGE, "plugin '" + info.getName() + "' cannot be installed like this, it is a system module");
+            throw new UserException(ExitCodes.USAGE, "plugin '" + info.getName() + "' cannot be installed like this, it is a system module");
         }
 
         // check for jar hell before any copying
@@ -475,7 +475,7 @@ private void install(Terminal terminal, boolean isBatch, Path tmpRoot, Environme
 
             final Path destination = env.pluginsFile().resolve(info.getName());
             if (Files.exists(destination)) {
-                throw new UserError(
+                throw new UserException(
                     ExitCodes.USAGE,
                     "plugin directory " + destination.toAbsolutePath() +
                         " already exists. To update the plugin, uninstall it first using 'remove " + info.getName() + "' command");
@@ -520,15 +520,15 @@ private void install(Terminal terminal, boolean isBatch, Path tmpRoot, Environme
     /** Copies the files from {@code tmpBinDir} into {@code destBinDir}, along with permissions from dest dirs parent. */
     private void installBin(PluginInfo info, Path tmpBinDir, Path destBinDir) throws Exception {
         if (Files.isDirectory(tmpBinDir) == false) {
-            throw new UserError(ExitCodes.IO_ERROR, "bin in plugin " + info.getName() + " is not a directory");
+            throw new UserException(ExitCodes.IO_ERROR, "bin in plugin " + info.getName() + " is not a directory");
         }
         Files.createDirectory(destBinDir);
         setFileAttributes(destBinDir, DIR_AND_EXECUTABLE_PERMS);
 
         try (DirectoryStream<Path> stream = Files.newDirectoryStream(tmpBinDir)) {
             for (Path srcFile : stream) {
                 if (Files.isDirectory(srcFile)) {
-                    throw new UserError(
+                    throw new UserException(
                         ExitCodes.DATA_ERROR,
                         "Directories not allowed in bin dir for plugin " + info.getName() + ", found " + srcFile.getFileName());
                 }
@@ -547,7 +547,7 @@ private void installBin(PluginInfo info, Path tmpBinDir, Path destBinDir) throws
      */
     private void installConfig(PluginInfo info, Path tmpConfigDir, Path destConfigDir) throws Exception {
         if (Files.isDirectory(tmpConfigDir) == false) {
-            throw new UserError(ExitCodes.IO_ERROR, "config in plugin " + info.getName() + " is not a directory");
+            throw new UserException(ExitCodes.IO_ERROR, "config in plugin " + info.getName() + " is not a directory");
         }
 
         Files.createDirectories(destConfigDir);
@@ -563,7 +563,7 @@ private void installConfig(PluginInfo info, Path tmpConfigDir, Path destConfigDi
         try (DirectoryStream<Path> stream = Files.newDirectoryStream(tmpConfigDir)) {
             for (Path srcFile : stream) {
                 if (Files.isDirectory(srcFile)) {
-                    throw new UserError(ExitCodes.DATA_ERROR, "Directories not allowed in config dir for plugin " + info.getName());
+                    throw new UserException(ExitCodes.DATA_ERROR, "Directories not allowed in config dir for plugin " + info.getName());
                 }
 
                 Path destFile = destConfigDir.resolve(tmpConfigDir.relativize(srcFile));

core/src/main/java/org/elasticsearch/plugins/RemovePluginCommand.java

@@ -29,10 +29,9 @@
 import joptsimple.OptionSet;
 import joptsimple.OptionSpec;
 import org.apache.lucene.util.IOUtils;
-import org.elasticsearch.cli.Command;
 import org.elasticsearch.cli.ExitCodes;
 import org.elasticsearch.cli.SettingCommand;
-import org.elasticsearch.cli.UserError;
+import org.elasticsearch.cli.UserException;
 import org.elasticsearch.common.Strings;
 import org.elasticsearch.cli.Terminal;
 import org.elasticsearch.common.settings.Settings;
@@ -58,7 +57,7 @@ protected void execute(Terminal terminal, OptionSet options, Map<String, String>
         // TODO: in jopt-simple 5.0 we can enforce a min/max number of positional args
         List<String> args = arguments.values(options);
         if (args.size() != 1) {
-            throw new UserError(ExitCodes.USAGE, "Must supply a single plugin id argument");
+            throw new UserException(ExitCodes.USAGE, "Must supply a single plugin id argument");
         }
         execute(terminal, args.get(0), settings);
     }
@@ -71,15 +70,15 @@ void execute(Terminal terminal, String pluginName, Map<String, String> settings)
 
         Path pluginDir = env.pluginsFile().resolve(pluginName);
         if (Files.exists(pluginDir) == false) {
-            throw new UserError(ExitCodes.USAGE, "plugin " + pluginName + " not found; run 'elasticsearch-plugin list' to get list of installed plugins");
+            throw new UserException(ExitCodes.USAGE, "plugin " + pluginName + " not found; run 'elasticsearch-plugin list' to get list of installed plugins");
         }
 
         List<Path> pluginPaths = new ArrayList<>();
 
         Path pluginBinDir = env.binFile().resolve(pluginName);
         if (Files.exists(pluginBinDir)) {
             if (Files.isDirectory(pluginBinDir) == false) {
-                throw new UserError(ExitCodes.IO_ERROR, "Bin dir for " + pluginName + " is not a directory");
+                throw new UserException(ExitCodes.IO_ERROR, "Bin dir for " + pluginName + " is not a directory");
             }
             pluginPaths.add(pluginBinDir);
             terminal.println(VERBOSE, "Removing: " + pluginBinDir);

core/src/test/java/org/elasticsearch/cli/CommandTests.java

@@ -30,7 +30,7 @@ static class UserErrorCommand extends Command {
         }
         @Override
         protected void execute(Terminal terminal, OptionSet options) throws Exception {
-            throw new UserError(ExitCodes.DATA_ERROR, "Bad input");
+            throw new UserException(ExitCodes.DATA_ERROR, "Bad input");
         }
     }
 
@@ -40,7 +40,7 @@ static class UsageErrorCommand extends Command {
         }
         @Override
         protected void execute(Terminal terminal, OptionSet options) throws Exception {
-            throw new UserError(ExitCodes.USAGE, "something was no good");
+            throw new UserException(ExitCodes.USAGE, "something was no good");
         }
     }
 
@@ -87,7 +87,7 @@ public void testVerbositySilentAndVerbose() throws Exception {
         MockTerminal terminal = new MockTerminal();
         NoopCommand command = new NoopCommand();
         String[] args = {"-v", "-s"};
-        UserError e = expectThrows(UserError.class, () -> {
+        UserException e = expectThrows(UserException.class, () -> {
             command.mainWithoutErrorHandling(args, terminal);
         });
         assertTrue(e.getMessage(), e.getMessage().contains("Cannot specify -s and -v together"));

core/src/test/java/org/elasticsearch/cli/MultiCommandTests.java

@@ -61,7 +61,7 @@ public void testNoCommandsConfigured() throws Exception {
 
     public void testUnknownCommand() throws Exception {
         multiCommand.subcommands.put("something", new DummySubCommand());
-        UserError e = expectThrows(UserError.class, () -> {
+        UserException e = expectThrows(UserException.class, () -> {
             execute("somethingelse");
         });
         assertEquals(ExitCodes.USAGE, e.exitCode);
@@ -70,7 +70,7 @@ public void testUnknownCommand() throws Exception {
 
     public void testMissingCommand() throws Exception {
         multiCommand.subcommands.put("command1", new DummySubCommand());
-        UserError e = expectThrows(UserError.class, () -> {
+        UserException e = expectThrows(UserException.class, () -> {
             execute();
         });
         assertEquals(ExitCodes.USAGE, e.exitCode);