Support exception handling with annotated methods

- New annotations ExceptionResolver and ExitCode
- New needed functionality is in classes ExceptionResolverMethodResolver
  and MethodCommandExceptionResolver.
- Hook these annotations with StandardMethodTargetRegistrar and Shell classes
- Fixes #597

Author: jvalkeal

spring-shell-core/src/main/java/org/springframework/shell/Shell.java

@@ -252,7 +252,12 @@ private Object evaluate(Input input) {
 			return ute.getCause();
 		}
 		catch (CommandExecutionException e1) {
-			return e1.getCause();
+			if (e1.getCause() instanceof Exception e11) {
+				e = e11;
+			}
+			else {
+				return e1.getCause();
+			}
 		}
 		catch (Exception e2) {
 			e = e2;
@@ -265,9 +270,13 @@ private Object evaluate(Input input) {
 				CommandHandlingResult processException = processException(commandExceptionResolvers, e);
 				processExceptionNonInt = processException;
 				if (processException != null) {
-					handlingResultNonInt = e;
-					this.terminal.writer().append(processException.message());
-					this.terminal.writer().flush();
+					if (processException.isPresent()) {
+						handlingResultNonInt = e;
+						if (StringUtils.hasText(processException.message())) {
+							this.terminal.writer().append(processException.message());
+							this.terminal.writer().flush();
+						}
+					}
 					return null;
 				}
 			} catch (Exception e1) {
@@ -298,12 +307,7 @@ private CommandHandlingResult processException(List<CommandExceptionResolver> co
 			}
 		}
 		if (r != null) {
-			if (r.isEmpty()) {
-				return null;
-			}
-			else {
-				return r;
-			}
+			return r;
 		}
 		throw e;
 	}

spring-shell-core/src/main/java/org/springframework/shell/command/CommandHandlingResult.java

@@ -25,60 +25,60 @@
 public interface CommandHandlingResult {
 
 	/**
-	 * Gets a message for this {@code HandlingResult}.
+	 * Gets a message for this {@code CommandHandlingResult}.
 	 *
 	 * @return a message
 	 */
 	@Nullable
 	String message();
 
 	/**
-	 * Gets an exit code for this {@code HandlingResult}. Exit code only has meaning
+	 * Gets an exit code for this {@code CommandHandlingResult}. Exit code only has meaning
 	 * if shell is in non-interactive mode.
 	 *
 	 * @return an exit code
 	 */
 	Integer exitCode();
 
 	/**
-	 * Indicate whether this {@code HandlingResult} has a result.
+	 * Indicate whether this {@code CommandHandlingResult} has a result.
 	 *
 	 * @return true if result exist
 	 */
 	public boolean isPresent();
 
 	/**
-	 * Indicate whether this {@code HandlingResult} does not have a result.
+	 * Indicate whether this {@code CommandHandlingResult} does not have a result.
 	 *
 	 * @return true if result doesn't exist
 	 */
 	public boolean isEmpty();
 
 	/**
-	 * Gets an empty instance of {@code HandlingResult}.
+	 * Gets an empty instance of {@code CommandHandlingResult}.
 	 *
-	 * @return empty instance of {@code HandlingResult}
+	 * @return empty instance of {@code CommandHandlingResult}
 	 */
 	public static CommandHandlingResult empty() {
 		return of(null);
 	}
 
 	/**
-	 * Gets an instance of {@code HandlingResult}.
+	 * Gets an instance of {@code CommandHandlingResult}.
 	 *
 	 * @param message the message
-	 * @return instance of {@code HandlingResult}
+	 * @return instance of {@code CommandHandlingResult}
 	 */
 	public static CommandHandlingResult of(@Nullable String message) {
 		return of(message, null);
 	}
 
 	/**
-	 * Gets an instance of {@code HandlingResult}.
+	 * Gets an instance of {@code CommandHandlingResult}.
 	 *
 	 * @param message the message
 	 * @param exitCode the exit code
-	 * @return instance of {@code HandlingResult}
+	 * @return instance of {@code CommandHandlingResult}
 	 */
 	public static CommandHandlingResult of(@Nullable String message, Integer exitCode) {
 		return new DefaultHandlingResult(message, exitCode);

spring-shell-core/src/main/java/org/springframework/shell/command/annotation/ExceptionResolver.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2022 the original author or authors.
+ *
+ * Licensed 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
+ *
+ *      https://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.springframework.shell.command.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.springframework.aot.hint.annotation.Reflective;
+
+/**
+ * Annotation for handling exceptions in specific command classes and/or its methods.
+ *
+ * @author Janne Valkealahti
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@Documented
+@Reflective
+public @interface ExceptionResolver {
+
+	/**
+	 * Exceptions handled by the annotated method. If empty, will default to any
+	 * exceptions listed in the method argument list.
+	 *
+	 * @return Exceptions handled by annotated method
+	 */
+	Class<? extends Throwable>[] value() default {};
+}

spring-shell-core/src/main/java/org/springframework/shell/command/annotation/ExceptionResolverMethodResolver.java

@@ -0,0 +1,186 @@
+/*
+ * Copyright 2022 the original author or authors.
+ *
+ * Licensed 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
+ *
+ *      https://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.springframework.shell.command.annotation;
+
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.springframework.core.ExceptionDepthComparator;
+import org.springframework.core.MethodIntrospector;
+import org.springframework.core.annotation.AnnotatedElementUtils;
+import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
+import org.springframework.util.ConcurrentReferenceHashMap;
+import org.springframework.util.ReflectionUtils.MethodFilter;
+
+/**
+ *
+ * @author Janne Valkealahti
+ */
+public class ExceptionResolverMethodResolver {
+
+	private static final MethodFilter EXCEPTION_HANDLER_METHODS = method ->
+			AnnotatedElementUtils.hasAnnotation(method, ExceptionResolver.class);
+	private static final Method NO_MATCHING_EXCEPTION_HANDLER_METHOD;
+	private final Map<Class<? extends Throwable>, Method> mappedMethods = new HashMap<>(16);
+	private final Map<Class<? extends Throwable>, Method> exceptionLookupCache = new ConcurrentReferenceHashMap<>(16);
+
+	static {
+		try {
+			NO_MATCHING_EXCEPTION_HANDLER_METHOD =
+					ExceptionResolverMethodResolver.class.getDeclaredMethod("noMatchingExceptionHandler");
+		}
+		catch (NoSuchMethodException ex) {
+			throw new IllegalStateException("Expected method not found: " + ex);
+		}
+	}
+
+	/**
+	 * A constructor that finds {@link ExceptionResolver} methods in the given type.
+	 *
+	 * @param handlerType the type to introspect
+	 */
+	public ExceptionResolverMethodResolver(Class<?> handlerType) {
+		for (Method method : MethodIntrospector.selectMethods(handlerType, EXCEPTION_HANDLER_METHODS)) {
+			for (Class<? extends Throwable> exceptionType : detectExceptionMappings(method)) {
+				addExceptionMapping(exceptionType, method);
+			}
+		}
+	}
+
+	/**
+	 * Extract exception mappings from the {@code @ExceptionResolver} annotation first,
+	 * and then as a fallback from the method signature itself.
+	 */
+	@SuppressWarnings("unchecked")
+	private List<Class<? extends Throwable>> detectExceptionMappings(Method method) {
+		List<Class<? extends Throwable>> result = new ArrayList<>();
+		detectAnnotationExceptionMappings(method, result);
+		if (result.isEmpty()) {
+			for (Class<?> paramType : method.getParameterTypes()) {
+				if (Throwable.class.isAssignableFrom(paramType)) {
+					result.add((Class<? extends Throwable>) paramType);
+				}
+			}
+		}
+		if (result.isEmpty()) {
+			throw new IllegalStateException("No exception types mapped to " + method);
+		}
+		return result;
+	}
+
+	private void detectAnnotationExceptionMappings(Method method, List<Class<? extends Throwable>> result) {
+		ExceptionResolver ann = AnnotatedElementUtils.findMergedAnnotation(method, ExceptionResolver.class);
+		Assert.state(ann != null, "No ExceptionResolver annotation");
+		result.addAll(Arrays.asList(ann.value()));
+	}
+
+	private void addExceptionMapping(Class<? extends Throwable> exceptionType, Method method) {
+		Method oldMethod = this.mappedMethods.put(exceptionType, method);
+		if (oldMethod != null && !oldMethod.equals(method)) {
+			throw new IllegalStateException("Ambiguous @ExceptionResolver method mapped for [" +
+					exceptionType + "]: {" + oldMethod + ", " + method + "}");
+		}
+	}
+
+	/**
+	 * Whether the contained type has any exception mappings.
+	 */
+	public boolean hasExceptionMappings() {
+		return !this.mappedMethods.isEmpty();
+	}
+
+	/**
+	 * Find a {@link Method} to handle the given exception.
+	 * <p>Uses {@link ExceptionDepthComparator} if more than one match is found.
+	 * @param exception the exception
+	 * @return a Method to handle the exception, or {@code null} if none found
+	 */
+	@Nullable
+	public Method resolveMethod(Exception exception) {
+		return resolveMethodByThrowable(exception);
+	}
+
+	/**
+	 * Find a {@link Method} to handle the given Throwable.
+	 * <p>Uses {@link ExceptionDepthComparator} if more than one match is found.
+	 *
+	 * @param exception the exception
+	 * @return a Method to handle the exception, or {@code null} if none found
+	 */
+	@Nullable
+	public Method resolveMethodByThrowable(Throwable exception) {
+		Method method = resolveMethodByExceptionType(exception.getClass());
+		if (method == null) {
+			Throwable cause = exception.getCause();
+			if (cause != null) {
+				method = resolveMethodByThrowable(cause);
+			}
+		}
+		return method;
+	}
+
+	/**
+	 * Find a {@link Method} to handle the given exception type. This can be
+	 * useful if an {@link Exception} instance is not available (e.g. for tools).
+	 * <p>Uses {@link ExceptionDepthComparator} if more than one match is found.
+	 *
+	 * @param exceptionType the exception type
+	 * @return a Method to handle the exception, or {@code null} if none found
+	 */
+	@Nullable
+	public Method resolveMethodByExceptionType(Class<? extends Throwable> exceptionType) {
+		Method method = this.exceptionLookupCache.get(exceptionType);
+		if (method == null) {
+			method = getMappedMethod(exceptionType);
+			this.exceptionLookupCache.put(exceptionType, method);
+		}
+		return (method != NO_MATCHING_EXCEPTION_HANDLER_METHOD ? method : null);
+	}
+
+	/**
+	 * Return the {@link Method} mapped to the given exception type, or
+	 * {@link #NO_MATCHING_EXCEPTION_HANDLER_METHOD} if none.
+	 */
+	private Method getMappedMethod(Class<? extends Throwable> exceptionType) {
+		List<Class<? extends Throwable>> matches = new ArrayList<>();
+		for (Class<? extends Throwable> mappedException : this.mappedMethods.keySet()) {
+			if (mappedException.isAssignableFrom(exceptionType)) {
+				matches.add(mappedException);
+			}
+		}
+		if (!matches.isEmpty()) {
+			if (matches.size() > 1) {
+				matches.sort(new ExceptionDepthComparator(exceptionType));
+			}
+			return this.mappedMethods.get(matches.get(0));
+		}
+		else {
+			return NO_MATCHING_EXCEPTION_HANDLER_METHOD;
+		}
+	}
+
+	/**
+	 * For the {@link #NO_MATCHING_EXCEPTION_HANDLER_METHOD} constant.
+ 	 */
+	@SuppressWarnings("unused")
+	private void noMatchingExceptionHandler() {
+	}
+}