From d3c4cf004d23030b6ec3c5595d2129750a33811e Mon Sep 17 00:00:00 2001 From: Gerd Behrmann Date: Sat, 5 Mar 2016 14:02:57 +0100 Subject: [PATCH] cells: Document and rename onerror commands Motivation: Provide docmentation for cell commands. Modification: Renames show onexit to show onerror and marks show onexit as deprecated. Extend command help printer to recognize deprecated commands. Deprecated commands are not included in the command list, but the full help information is available. For annotated commands the help output warns that the command is deprecated. Refactors the onerror state of the command interpreter to use an enum instead of a string. Result: show onexit is deprecated; use show onerror instead. Better cell command documentation. Target: trunk Require-notes: yes Require-book: yes Acked-by: Paul Millar Patch: https://rb.dcache.org/r/9109/ --- .../java/dmg/cells/nucleus/CellShell.java | 91 +++++++++++++------ .../dmg/util/command/AcCommandExecutor.java | 8 ++ .../dmg/util/command/TextHelpPrinter.java | 5 + .../util/cli/AnnotatedCommandExecutor.java | 11 ++- .../org/dcache/util/cli/CommandExecutor.java | 5 + .../dcache/util/cli/CommandInterpreter.java | 2 +- 6 files changed, 92 insertions(+), 30 deletions(-) diff --git a/modules/cells/src/main/java/dmg/cells/nucleus/CellShell.java b/modules/cells/src/main/java/dmg/cells/nucleus/CellShell.java index e0eae391a2b..704d4650a31 100644 --- a/modules/cells/src/main/java/dmg/cells/nucleus/CellShell.java +++ b/modules/cells/src/main/java/dmg/cells/nucleus/CellShell.java @@ -82,6 +82,11 @@ public class CellShell extends CommandInterpreter private static final Logger _logNucleus = LoggerFactory.getLogger(CellNucleus.class); + enum ErrorAction + { + SHUTDOWN, EXIT, CONTINUE + } + private final CellNucleus _nucleus ; private StringBuilder _contextString; private String _contextName; @@ -92,7 +97,7 @@ public class CellShell extends CommandInterpreter private int _helpMode = 1 ; private int _errorCode; private String _errorMsg; - private String _doOnExit; + private ErrorAction _doOnError = ErrorAction.CONTINUE; private final Map _environment = new ConcurrentHashMap<>(); private CommandInterpreter _externalInterpreter; @@ -276,15 +281,12 @@ public Object objectCommand( String strin ) throws CommandExitException { _errorCode = ce.getErrorCode() ; _errorMsg = ce.getErrorMessage() ; - if( _doOnExit != null ){ - if( _doOnExit.equals( "shutdown" ) ) { - throw new CommandExitException(ce.toString(), 666); - } else { - throw new CommandExitException(ce.getErrorMessage(), - ce.getErrorCode()); - } - - } + switch (_doOnError) { + case SHUTDOWN: + throw new CommandExitException(ce.toString(), 666); + case EXIT: + throw new CommandExitException(ce.getErrorMessage(), ce.getErrorCode()); + } if( ce instanceof CommandSyntaxException ){ CommandSyntaxException cse = (CommandSyntaxException)ce ; @@ -998,22 +1000,55 @@ public String call() throws ClassNotFoundException, NoSuchMethodException, } } - //////////////////////////////////////////////////////////// - // - // this and that - // - public static final String hh_onerror = "shutdown|exit|continue" ; - public String ac_onerror_$_1( Args args ){ - if( args.argv(0).equals( "continue" ) ) { - _doOnExit = null; - } else { - _doOnExit = args.argv(0); - } - return "" ; - } - public String ac_show_onexit( Args args ){ - return _doOnExit != null ? _doOnExit : "" ; - } + //////////////////////////////////////////////////////////// + // + // this and that + // + @Command(name = "onerror", hint = "set error action", + description = "Defines how the command interpreter reacts to processing errors.") + class OnErrorCommand implements Callable + { + @Argument(valueSpec = "shutdown|exit|continue", + usage = "shutdown:\n" + + "\tterminate dCache domain.\n" + + "exit:\n" + + "\tterminate interpreter.\n" + + "continue:\n" + + "\tignore error.") + ErrorAction action; + + @Override + public String call() + { + _doOnError = action; + return ""; + } + } + + @Command(name = "show onexit", hint = "show current error action", + description = "Shows how the command interpreter reacts to errors. The action can " + + "be set using the onerror command.") + @Deprecated + class ShowOnExitCommand implements Callable + { + @Override + public String call() + { + return _doOnError.toString().toLowerCase(); + } + } + + @Command(name = "show onerror", hint = "show current error action", + description = "Shows how the command interpreter reacts to errors. The action can " + + "be set using the onerror command.") + class ShowOnErrorCommand implements Callable + { + @Override + public String call() + { + return _doOnError.toString().toLowerCase(); + } + } private static final int PRINT_CELL = 1; @@ -1631,11 +1666,11 @@ public void execute(String source, Reader in, Writer out, Writer err, Args args) "information.", error.getCause()); } - if (_doOnExit != null) { + if (_doOnError != ErrorAction.CONTINUE) { String msg = String.format("%s: line %d: %s", source, no, error.getMessage()); - if (_doOnExit.equals("shutdown")) { + if (_doOnError == ErrorAction.SHUTDOWN) { throw new CommandExitException(msg, 666, error); } else if (error instanceof CommandException) { int rc = ((CommandException) error).getErrorCode(); diff --git a/modules/cells/src/main/java/dmg/util/command/AcCommandExecutor.java b/modules/cells/src/main/java/dmg/util/command/AcCommandExecutor.java index 235ad36efb8..e08643b9475 100644 --- a/modules/cells/src/main/java/dmg/util/command/AcCommandExecutor.java +++ b/modules/cells/src/main/java/dmg/util/command/AcCommandExecutor.java @@ -29,17 +29,25 @@ class AcCommandExecutor implements CommandExecutor private Field _fullHelp; private Field _helpHint; private Field _acls; + private boolean _isDeprecated; public AcCommandExecutor(Object listener) { _listener = listener; } + @Override + public boolean isDeprecated() + { + return _isDeprecated; + } + public void setMethod(Method m, int mn, int mx) { _method = m; _minArgs = mn; _maxArgs = mx; + _isDeprecated = m.getDeclaredAnnotation(Deprecated.class) != null; } public void setFullHelpField(Field f) { diff --git a/modules/common-cli/src/main/java/dmg/util/command/TextHelpPrinter.java b/modules/common-cli/src/main/java/dmg/util/command/TextHelpPrinter.java index 33c583a1301..0af250018a9 100644 --- a/modules/common-cli/src/main/java/dmg/util/command/TextHelpPrinter.java +++ b/modules/common-cli/src/main/java/dmg/util/command/TextHelpPrinter.java @@ -262,6 +262,11 @@ public String getHelp(Object instance) writer.append(Strings.wrap(" ", literal(command.name()) + " " + getSignature(clazz), WIDTH)); writer.println(); + if (clazz.getDeclaredAnnotation(Deprecated.class) != null) { + writer.append(Strings.wrap(" ", "This command is deprecated and will be removed in a future release.", WIDTH)); + writer.println(); + } + if (!command.description().isEmpty()) { writer.println(heading("DESCRIPTION")); writer.append(Strings.wrap(" ", command.description(), WIDTH)); diff --git a/modules/common-cli/src/main/java/org/dcache/util/cli/AnnotatedCommandExecutor.java b/modules/common-cli/src/main/java/org/dcache/util/cli/AnnotatedCommandExecutor.java index 1ff77675309..5c83e0e926c 100644 --- a/modules/common-cli/src/main/java/org/dcache/util/cli/AnnotatedCommandExecutor.java +++ b/modules/common-cli/src/main/java/org/dcache/util/cli/AnnotatedCommandExecutor.java @@ -68,6 +68,7 @@ public Integer apply(Handler handler) private final Command _command; private final Constructor> _constructor; private final List _handlers; + private final boolean _isDeprecated; public AnnotatedCommandExecutor(Object parent, Command command, Constructor> constructor) @@ -75,7 +76,15 @@ public AnnotatedCommandExecutor(Object parent, Command command, _parent = parent; _command = command; _constructor = constructor; - _handlers = createFieldHandlers(command, _constructor.getDeclaringClass()); + Class> commandClass = _constructor.getDeclaringClass(); + _handlers = createFieldHandlers(command, commandClass); + _isDeprecated = commandClass.getDeclaredAnnotation(Deprecated.class) != null; + } + + @Override + public boolean isDeprecated() + { + return _isDeprecated; } @Override diff --git a/modules/common-cli/src/main/java/org/dcache/util/cli/CommandExecutor.java b/modules/common-cli/src/main/java/org/dcache/util/cli/CommandExecutor.java index 381dbfe4f7e..edf99304cf0 100644 --- a/modules/common-cli/src/main/java/org/dcache/util/cli/CommandExecutor.java +++ b/modules/common-cli/src/main/java/org/dcache/util/cli/CommandExecutor.java @@ -13,6 +13,11 @@ */ public interface CommandExecutor { + /** + * Returns true if and only if the command is marked as deprecated. + */ + boolean isDeprecated(); + /** * Returns true if and only if the command has any ACLs. */ diff --git a/modules/common-cli/src/main/java/org/dcache/util/cli/CommandInterpreter.java b/modules/common-cli/src/main/java/org/dcache/util/cli/CommandInterpreter.java index ce9ca4d55b2..4fdfdd3b820 100644 --- a/modules/common-cli/src/main/java/org/dcache/util/cli/CommandInterpreter.java +++ b/modules/common-cli/src/main/java/org/dcache/util/cli/CommandInterpreter.java @@ -246,7 +246,7 @@ public boolean hasACLs() public void dumpHelpHint(String top, StringBuilder sb, HelpFormat format) { - if (_commandExecutor != null) { + if (_commandExecutor != null && !_commandExecutor.isDeprecated()) { String hint = _commandExecutor.getHelpHint(format); if (hint != null) { sb.append(top).append(hint).append("\n");