Add support for exception mapping

Author: fmbenhassine

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

@@ -20,8 +20,11 @@
 import java.util.List;
 import java.util.Objects;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.shell.core.command.availability.Availability;
 import org.springframework.shell.core.command.availability.AvailabilityProvider;
+import org.springframework.shell.core.command.exit.ExitStatusExceptionMapper;
 
 /**
  * Base class helping to build shell commands.
@@ -44,6 +47,8 @@ public abstract class AbstractCommand implements Command {
 
 	private AvailabilityProvider availabilityProvider = AvailabilityProvider.alwaysAvailable();
 
+	@Nullable private ExitStatusExceptionMapper exitStatusExceptionMapper;
+
 	private List<String> aliases = new ArrayList<>();
 
 	public AbstractCommand(String name, String description) {
@@ -105,6 +110,14 @@ public void setAvailabilityProvider(AvailabilityProvider availabilityProvider) {
 		this.availabilityProvider = availabilityProvider;
 	}
 
+	@Nullable public ExitStatusExceptionMapper getExitStatusExceptionMapper() {
+		return exitStatusExceptionMapper;
+	}
+
+	public void setExitStatusExceptionMapper(ExitStatusExceptionMapper exitStatusExceptionMapper) {
+		this.exitStatusExceptionMapper = exitStatusExceptionMapper;
+	}
+
 	@Override
 	public ExitStatus execute(CommandContext commandContext) throws Exception {
 		Availability availability = getAvailabilityProvider().get();
@@ -118,7 +131,17 @@ public ExitStatus execute(CommandContext commandContext) throws Exception {
 			println(getHelp(), commandContext);
 			return ExitStatus.OK;
 		}
-		return doExecute(commandContext);
+		try {
+			return doExecute(commandContext);
+		}
+		catch (Exception e) {
+			if (getExitStatusExceptionMapper() != null) {
+				return getExitStatusExceptionMapper().apply(e);
+			}
+			else {
+				throw e;
+			}
+		}
 	}
 
 	protected void println(String message, CommandContext commandContext) {

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

@@ -22,9 +22,12 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.shell.core.command.adapter.ConsumerCommandAdapter;
 import org.springframework.shell.core.command.adapter.FunctionCommandAdapter;
 import org.springframework.shell.core.command.availability.AvailabilityProvider;
+import org.springframework.shell.core.command.exit.ExitStatusExceptionMapper;
 import org.springframework.util.Assert;
 
 /**
@@ -127,6 +130,8 @@ final class Builder {
 
 		private AvailabilityProvider availabilityProvider = AvailabilityProvider.alwaysAvailable();
 
+		@Nullable ExitStatusExceptionMapper exitStatusExceptionMapper;
+
 		private List<String> aliases = new ArrayList<>();
 
 		public Builder name(String name) {
@@ -159,6 +164,11 @@ public Builder availabilityProvider(AvailabilityProvider availabilityProvider) {
 			return this;
 		}
 
+		public Builder exitStatusExceptionMapper(ExitStatusExceptionMapper exitStatusExceptionMapper) {
+			this.exitStatusExceptionMapper = exitStatusExceptionMapper;
+			return this;
+		}
+
 		public Builder aliases(String... aliases) {
 			this.aliases = Arrays.asList(aliases);
 			return this;
@@ -171,6 +181,9 @@ public AbstractCommand execute(Consumer<CommandContext> commandExecutor) {
 					commandExecutor);
 			command.setAliases(aliases);
 			command.setAvailabilityProvider(availabilityProvider);
+			if (exitStatusExceptionMapper != null) {
+				command.setExitStatusExceptionMapper(exitStatusExceptionMapper);
+			}
 
 			return command;
 		}
@@ -182,6 +195,9 @@ public AbstractCommand execute(Function<CommandContext, String> commandExecutor)
 					commandExecutor);
 			command.setAliases(aliases);
 			command.setAvailabilityProvider(availabilityProvider);
+			if (exitStatusExceptionMapper != null) {
+				command.setExitStatusExceptionMapper(exitStatusExceptionMapper);
+			}
 
 			return command;
 		}

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

@@ -93,4 +93,10 @@
 	 */
 	String availabilityProvider() default "";
 
+	/**
+	 * Define exit status exception mapper bean name.
+	 * @return the exit status exception mapper bean name
+	 */
+	String exitStatusExceptionMapper() default "";
+
 }

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

@@ -33,6 +33,7 @@
 import org.springframework.shell.core.command.CommandCreationException;
 import org.springframework.shell.core.command.adapter.MethodInvokerCommandAdapter;
 import org.springframework.shell.core.command.availability.AvailabilityProvider;
+import org.springframework.shell.core.command.exit.ExitStatusExceptionMapper;
 import org.springframework.util.Assert;
 
 /**
@@ -68,6 +69,7 @@ public Command getObject() {
 		boolean hidden = command.hidden();
 		String[] aliases = command.alias();
 		String availabilityProvider = command.availabilityProvider();
+		String exitStatusExceptionMapper = command.exitStatusExceptionMapper();
 		log.debug("Creating command bean for method '" + this.method + "' with name '" + name + "'");
 		Class<?> declaringClass = this.method.getDeclaringClass();
 		Object targetObject;
@@ -101,10 +103,24 @@ Ensure that the declaring class is annotated with a Spring stereotype annotation
 						+ "', using always available provider.");
 			}
 		}
+		ExitStatusExceptionMapper exitStatusExceptionMapperBean = null;
+		if (!exitStatusExceptionMapper.isEmpty()) {
+			try {
+				exitStatusExceptionMapperBean = this.applicationContext.getBean(exitStatusExceptionMapper,
+						ExitStatusExceptionMapper.class);
+			}
+			catch (BeansException e) {
+				log.debug("No ExitStatusExceptionMapper bean found with name '" + exitStatusExceptionMapper
+						+ "', using default exception mapping strategy.");
+			}
+		}
 		MethodInvokerCommandAdapter methodInvokerCommandAdapter = new MethodInvokerCommandAdapter(name, description,
 				group, help, hidden, this.method, targetObject, configurableConversionService);
 		methodInvokerCommandAdapter.setAliases(Arrays.stream(aliases).toList());
 		methodInvokerCommandAdapter.setAvailabilityProvider(availabilityProviderBean);
+		if (exitStatusExceptionMapperBean != null) {
+			methodInvokerCommandAdapter.setExitStatusExceptionMapper(exitStatusExceptionMapperBean);
+		}
 		return methodInvokerCommandAdapter;
 	}
 

…core/exit/ExitStatusExceptionMapper.java …mand/exit/ExitStatusExceptionMapper.javaspring-shell-core/src/main/java/org/springframework/shell/core/exit/ExitStatusExceptionMapper.java renamed to spring-shell-core/src/main/java/org/springframework/shell/core/command/exit/ExitStatusExceptionMapper.java spring-shell-core/src/main/java/org/springframework/shell/core/exit/ExitStatusExceptionMapper.java renamed to spring-shell-core/src/main/java/org/springframework/shell/core/command/exit/ExitStatusExceptionMapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 the original author or authors.
+ * Copyright 2022-present 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.
@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.springframework.shell.core.exit;
+package org.springframework.shell.core.command.exit;
 
 import java.util.function.Function;
 
@@ -24,6 +24,7 @@
  * implementing boot's {@code ExitCodeGenerator}.
  *
  * @author Janne Valkealahti
+ * @author Mahmoud Ben Hassine
  */
 public interface ExitStatusExceptionMapper extends Function<Exception, ExitStatus> {
 

…mework/shell/core/exit/package-info.java …hell/core/command/exit/package-info.javaspring-shell-core/src/main/java/org/springframework/shell/core/exit/package-info.java renamed to spring-shell-core/src/main/java/org/springframework/shell/core/command/exit/package-info.java spring-shell-core/src/main/java/org/springframework/shell/core/exit/package-info.java renamed to spring-shell-core/src/main/java/org/springframework/shell/core/command/exit/package-info.java

@@ -1,4 +1,4 @@
 @NullMarked
-package org.springframework.shell.core.exit;
+package org.springframework.shell.core.command.exit;
 
 import org.jspecify.annotations.NullMarked;

spring-shell-docs/modules/ROOT/nav.adoc

@@ -12,6 +12,7 @@
 ** xref:commands/context.adoc[]
 ** xref:commands/registry.adoc[]
 ** xref:commands/availability.adoc[]
+** xref:commands/exception-handling.adoc[]
 ** xref:commands/help.adoc[]
 ** xref:commands/builtin/index.adoc[]
 *** xref:commands/builtin/help.adoc[]

spring-shell-docs/modules/ROOT/pages/commands/exception-handling.adoc

@@ -0,0 +1,72 @@
+[[exception-handling]]
+= Exception Handling
+
+When writing commands, it is important to handle exceptions properly to ensure that your application behaves predictably in the face of errors.
+Spring Shell allows you to manage exceptions effectively and map them to specific exit codes and user-friendly messages thanks to the `ExitStatusExceptionMapper` interface.
+
+The `ExitStatusExceptionMapper` interface provides a way to map exceptions thrown during command execution to specific exit codes and messages.
+By implementing this interface, you can define custom behavior for different types of exceptions, allowing you to provide meaningful feedback to users and control the exit status of your application.
+
+== Implementing ExitStatusExceptionMapper
+
+The `ExitStatusExceptionMapper` is a functional interface that extends `java.util.Function`, and which takes an `Exception` as input and returns an `ExitStatus`.
+You can implement this method to handle specific exceptions and return appropriate exit codes and messages. For example:
+
+[source, java, indent=0]
+----
+@Bean
+public ExitStatusExceptionMapper myCustomExceptionMapper() {
+	return exception -> new ExitStatus(42, "42! The answer to life, the universe and everything!");
+}
+----
+
+== Registering the Mapper
+
+=== Programmatic Registration
+
+When registering commands programmatically, you can set the `ExitStatusExceptionMapper` using the `exitStatusExceptionMapper` method on the `Command.Builder`. For example:
+
+[source, java, indent=0]
+----
+@Bean
+public Command sayHello() {
+	return Command.builder()
+			.name("hello")
+			.description("Say hello to a given name")
+			.group("Greetings")
+			.help("A command that greets the user with 'Hello ${name}!'. Usage: hello [-n | --name]=<name>")
+			.exitStatusExceptionMapper(exception -> new ExitStatus(42, "42! The answer to life, the universe and everything!"))
+			.execute(context -> {
+				String name = context.getOptionByName("name").value();
+				if (name.equals("42")) {
+					throw new RuntimeException("Error!");
+				}
+				System.out.println("Hello " + name + "!");
+			});
+}
+----
+
+=== Annotation-Based Registration
+
+When using annotation-based command registration, you can specify the custom `ExitStatusExceptionMapper` by using the `exitStatusExceptionMapper` attribute of the `@Command` annotation. For example:
+
+[source, java, indent=0]
+----
+@Command(name = "hello", description = "Say hello to a given name", group = "Greetings",
+		help = "A command that greets the user with 'Hello ${name}!'. Usage: hello [-n | --name]=<name>",
+		exitStatusExceptionMapper = "myCustomExceptionMapper")
+public void sayHello(@Option(shortName = 'n', longName = "name", description = "the name of the person to greet",
+		defaultValue = "World") String name) {
+	if (name.equals("42")) {
+		throw new RuntimeException("Error!");
+	}
+	System.out.println("Hello " + name + "!");
+}
+
+@Bean
+public ExitStatusExceptionMapper myCustomExceptionMapper() {
+	return exception -> new ExitStatus(42, "42! The answer to life, the universe and everything!");
+}
+----
+
+The custom mapper should be defined as a Spring bean so that it can be referenced by name in the `@Command` annotation.