Add support for option validation with the Bean Validation API

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 jakarta.validation.Path;
+
 import org.jspecify.annotations.Nullable;
 
+import org.springframework.shell.core.ParameterValidationException;
 import org.springframework.shell.core.command.availability.Availability;
 import org.springframework.shell.core.command.availability.AvailabilityProvider;
 import org.springframework.shell.core.command.exit.ExitStatusExceptionMapper;
@@ -134,6 +137,17 @@ public ExitStatus execute(CommandContext commandContext) throws Exception {
 		try {
 			return doExecute(commandContext);
 		}
+		catch (ParameterValidationException parameterValidationException) {
+			PrintWriter outputWriter = commandContext.outputWriter();
+			outputWriter.println("The following constraints were not met:");
+			parameterValidationException.getConstraintViolations().forEach(violation -> {
+				Path propertyPath = violation.getPropertyPath();
+				String violationMessage = violation.getMessage();
+				String errorMessage = String.format("\t--%s: %s", extractPropertyName(propertyPath), violationMessage);
+				outputWriter.println(errorMessage);
+			});
+			return ExitStatus.USAGE_ERROR;
+		}
 		catch (Exception e) {
 			if (getExitStatusExceptionMapper() != null) {
 				return getExitStatusExceptionMapper().apply(e);
@@ -144,6 +158,12 @@ public ExitStatus execute(CommandContext commandContext) throws Exception {
 		}
 	}
 
+	private String extractPropertyName(Path propertyPath) {
+		String path = propertyPath.toString();
+		int lastIndexOfDot = path.lastIndexOf(".");
+		return lastIndexOfDot == -1 ? path : path.substring(lastIndexOfDot + 1);
+	}
+
 	protected void println(String message, CommandContext commandContext) {
 		PrintWriter outputWriter = commandContext.outputWriter();
 		outputWriter.println(message);

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

@@ -19,16 +19,24 @@
 import java.lang.reflect.Parameter;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Set;
+
+import jakarta.validation.ConstraintViolation;
+import jakarta.validation.Validator;
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
 import org.springframework.core.convert.support.ConfigurableConversionService;
-import org.springframework.shell.core.command.*;
+import org.springframework.shell.core.ParameterValidationException;
+import org.springframework.shell.core.command.AbstractCommand;
+import org.springframework.shell.core.command.CommandArgument;
+import org.springframework.shell.core.command.CommandContext;
+import org.springframework.shell.core.command.CommandOption;
+import org.springframework.shell.core.command.ExitStatus;
 import org.springframework.shell.core.command.annotation.Argument;
 import org.springframework.shell.core.command.annotation.Arguments;
 import org.springframework.shell.core.command.annotation.Option;
-import org.springframework.shell.core.command.AbstractCommand;
 import org.springframework.util.MethodInvoker;
 
 /**
@@ -45,6 +53,8 @@ public class MethodInvokerCommandAdapter extends AbstractCommand {
 
 	private final Object targetObject;
 
+	private final Validator validator;
+
 	private final ConfigurableConversionService conversionService;
 
 	/**
@@ -59,11 +69,12 @@ public class MethodInvokerCommandAdapter extends AbstractCommand {
 	 * @param conversionService the conversion service to use for parameter conversion
 	 */
 	public MethodInvokerCommandAdapter(String name, String description, String group, String help, boolean hidden,
-			Method method, Object targetObject, ConfigurableConversionService conversionService) {
+			Method method, Object targetObject, ConfigurableConversionService conversionService, Validator validator) {
 		super(name, description, group, help, hidden);
 		this.method = method;
 		this.targetObject = targetObject;
 		this.conversionService = conversionService;
+		this.validator = validator;
 	}
 
 	@Override
@@ -79,16 +90,25 @@ public ExitStatus doExecute(CommandContext commandContext) throws Exception {
 		Class<?>[] parameterTypes = this.method.getParameterTypes();
 
 		// TODO should be able to mix CommandContext and other parameters
+		Object[] argumentsArray = null;
 		if (parameterTypes.length == 1
 				&& parameterTypes[0].equals(org.springframework.shell.core.command.CommandContext.class)) {
-			methodInvoker.setArguments(commandContext);
+			argumentsArray = new Object[] { commandContext };
 		}
 		else {
 			List<Object> arguments = prepareArguments(commandContext);
-			methodInvoker.setArguments(arguments.toArray());
+			argumentsArray = arguments.toArray();
 		}
+		methodInvoker.setArguments(argumentsArray);
 		methodInvoker.prepare();
 
+		// validate parameters
+		Set<ConstraintViolation<Object>> constraintViolations = validator.forExecutables()
+			.validateParameters(targetObject, method, argumentsArray);
+		if (!constraintViolations.isEmpty()) {
+			throw new ParameterValidationException(constraintViolations);
+		}
+
 		// invoke method
 		methodInvoker.invoke();
 		commandContext.outputWriter().flush();

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

@@ -18,6 +18,8 @@
 import java.lang.reflect.Method;
 import java.util.Arrays;
 
+import jakarta.validation.Validator;
+
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
@@ -34,6 +36,7 @@
 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.shell.core.utils.Utils;
 import org.springframework.util.Assert;
 
 /**
@@ -114,8 +117,15 @@ Ensure that the declaring class is annotated with a Spring stereotype annotation
 						+ "', using default exception mapping strategy.");
 			}
 		}
+		Validator validator = Utils.defaultValidator();
+		try {
+			validator = this.applicationContext.getBean(Validator.class);
+		}
+		catch (BeansException e) {
+			log.debug("No Validator bean found, using default validator.");
+		}
 		MethodInvokerCommandAdapter methodInvokerCommandAdapter = new MethodInvokerCommandAdapter(name, description,
-				group, help, hidden, this.method, targetObject, configurableConversionService);
+				group, help, hidden, this.method, targetObject, configurableConversionService, validator);
 		methodInvokerCommandAdapter.setAliases(Arrays.stream(aliases).toList());
 		methodInvokerCommandAdapter.setAvailabilityProvider(availabilityProviderBean);
 		if (exitStatusExceptionMapperBean != null) {

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

@@ -9,6 +9,7 @@
 ** xref:commands/registration/annotation.adoc[]
 ** xref:commands/organize.adoc[]
 ** xref:commands/syntax.adoc[]
+** xref:commands/validation.adoc[]
 ** xref:commands/context.adoc[]
 ** xref:commands/registry.adoc[]
 ** xref:commands/availability.adoc[]

spring-shell-docs/modules/ROOT/pages/commands/syntax.adoc

@@ -13,7 +13,9 @@ include::{snippets}/CommandAnnotationSnippets.java[tag=command-option-arg]
 ----
 
 Options are defined using `@Option` annotation, while arguments are defined using `@Argument` annotation.
-Options are named, while arguments are positional.
+Options are named, while arguments are positional. Options can have short names (single character) and long names (multi-character).
+
+Options can be validated using the Bean Validation API by adding validation annotations to the method parameters, see the xref:commands/validation.adoc[Validating Command Options] section for more details.
 
 == Parsing rules
 

spring-shell-docs/modules/ROOT/pages/commands/validation.adoc

@@ -0,0 +1,28 @@
+[[validating-command-options]]
+= Option Validation
+
+Spring Shell integrates with the https://beanvalidation.org/[Bean Validation API] to support
+automatic and self-documenting constraints on command parameters.
+
+Annotations found on command parameters are honored and trigger validation prior to the command executing.
+Consider the following command:
+
+[source, java]
+----
+@Command(name = "change-password", description = "Change password", group = "User Management",
+		help = "A command that changes the user password. Usage: change-password [-p | --password]=<password>")
+public String changePassword(
+		@Option(shortName = 'p', longName = "password") @Size(min = 8, max = 40) String password) {
+	return "Password successfully set to " + password;
+}
+----
+
+From the preceding example, you get the following behavior for free:
+
+[source, bash]
+----
+$>change-password --password=hello
+The following constraints were not met:
+	--password: size must be between 8 and 40
+Error while executing command change-password: USAGE_ERROR
+----