feature: pluggable exception mapping to ValidationResult for Business Logic

- fix #3937

Author: jknack

jooby/src/main/java/io/jooby/ModelAndView.java

@@ -77,6 +77,27 @@ public static MapModelAndView map(String view, Map<String, Object> model) {
     return new MapModelAndView(view, model);
   }
 
+  /**
+   * Creates a model and view based on the provided view name and model. If the model is null, a
+   * map-based model and view is created. If the model is an instance of {@code Map}, a map-based
+   * model and view is created using the provided map. Otherwise, a generic model and view is
+   * created with the specified view name and model.
+   *
+   * @param view The name of the view, which may include a file extension.
+   * @param model The data model to be associated with the view. This can be null, a {@code Map}, or
+   *     any other object.
+   * @return A {@code ModelAndView} instance corresponding to the specified view and model.
+   */
+  public static ModelAndView<Map<String, Object>> of(String view, Object model) {
+    if (model == null) {
+      return map(view);
+    }
+    if (model instanceof Map mapModel) {
+      return map(view, mapModel);
+    }
+    return new ModelAndView(view, model);
+  }
+
   /**
    * Sets the locale used when rendering the view, if the template engine supports setting it.
    * Specifying {@code null} triggers a fallback to a locale determined by the current request.

jooby/src/main/java/io/jooby/internal/RouterImpl.java

@@ -43,6 +43,7 @@
 import io.jooby.internal.handler.WebSocketHandler;
 import io.jooby.output.OutputFactory;
 import io.jooby.problem.ProblemDetailsHandler;
+import io.jooby.validation.ValidationExceptionMapper;
 import io.jooby.value.ValueFactory;
 
 public class RouterImpl implements Router {
@@ -551,6 +552,15 @@ public Router start(Jooby app) {
     } else {
       err = err.then(globalErrHandler);
     }
+    // Validation mapper
+    var services = app.getServices();
+    List<ValidationExceptionMapper> validationExceptionMappers =
+        services.getOrNull(Reified.list(ValidationExceptionMapper.class));
+    var validationExceptionChain = new ValidationExceptionChain();
+    if (validationExceptionMappers != null) {
+      validationExceptionMappers.forEach(validationExceptionChain::add);
+    }
+    services.put(ValidationExceptionMapper.class, validationExceptionChain);
 
     ExecutionMode mode = app.getExecutionMode();
     for (Route route : routes) {

jooby/src/main/java/io/jooby/internal/ValidationExceptionChain.java

@@ -0,0 +1,90 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.internal;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+
+import org.jspecify.annotations.NonNull;
+
+import io.jooby.SneakyThrows;
+import io.jooby.StatusCode;
+import io.jooby.validation.ValidationExceptionMapper;
+import io.jooby.validation.ValidationResult;
+
+/**
+ * ValidationExceptionChain provides a way to combine multiple {@link ValidationExceptionMapper}
+ * implementations into a single chain. This allows sequential delegation of validation exception
+ * mapping to the contained mappers.
+ *
+ * <p>The chain processes exceptions by iterating over the registered mappers. Each mapper attempts
+ * to convert the given exception into a {@link ValidationResult}. The first non-null result found
+ * is returned. If none of the mappers produce a result, a default {@link ValidationResult} is
+ * generated with a global error indicating validation failure.
+ *
+ * <p>This class is useful in scenarios where different exception mapping strategies are needed and
+ * should be applied in a specific sequence.
+ *
+ * @author edgar
+ * @since 4.5.0
+ */
+public class ValidationExceptionChain implements ValidationExceptionMapper {
+  private final List<ValidationExceptionMapper> mappers = new ArrayList<>();
+
+  /**
+   * Adds a {@link ValidationExceptionMapper} to the chain.
+   *
+   * <p>This method allows the registration of a new mapper, which will be used in sequence for
+   * exception mapping. The newly added mapper will be appended to the chain, maintaining the order
+   * of insertion.
+   *
+   * @param mapper the {@link ValidationExceptionMapper} to be added to the chain
+   * @return the current {@link ValidationExceptionChain} instance to allow for method chaining
+   */
+  public ValidationExceptionChain add(ValidationExceptionMapper mapper) {
+    mappers.add(mapper);
+    return this;
+  }
+
+  /**
+   * Converts the given {@link StatusCode} and {@link Exception} into a {@link ValidationResult}.
+   *
+   * <p>This method iterates through the chain of registered {@link ValidationExceptionMapper}
+   * instances. Each mapper attempts to produce a {@link ValidationResult} for the specified status
+   * code and exception. If a non-null result is produced, it is returned immediately. If no mapper
+   * produces a valid result, a default {@link ValidationResult} is returned indicating a global
+   * validation failure.
+   *
+   * @param suggestedCode the status code associated with the exception
+   * @param cause the exception that needs to be converted into a validation result
+   * @return the converted {@link ValidationResult} from the first applicable mapper, or a default
+   *     result if no mapper can process the exception
+   */
+  @Override
+  public @NonNull ValidationResult toResult(StatusCode suggestedCode, Exception cause) {
+    for (var mapper : mappers) {
+      var result = mapper.toResult(suggestedCode, cause);
+      if (result != null) {
+        return result;
+      }
+    }
+    if (suggestedCode.value() >= 500) {
+      throw SneakyThrows.propagate(cause);
+    }
+    // Assume is a client error, provide a default result
+    return new ValidationResult(
+        "Validation failed",
+        suggestedCode.value(),
+        List.of(
+            new ValidationResult.Error(
+                null,
+                List.of(
+                    Optional.ofNullable(cause.getMessage())
+                        .orElse(cause.getClass().getSimpleName())),
+                ValidationResult.ErrorType.GLOBAL)));
+  }
+}

jooby/src/main/java/io/jooby/validation/ValidationExceptionMapper.java

@@ -0,0 +1,40 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.validation;
+
+import org.jspecify.annotations.Nullable;
+
+import io.jooby.StatusCode;
+
+/**
+ * This interface defines a contract for mapping exceptions to validation results. It is primarily
+ * used to convert exceptions, such as those thrown during bean validation, into instances of {@link
+ * ValidationResult}. This allows for a consistent representation of validation errors across the
+ * application.
+ *
+ * <p>Implementers are responsible for interpreting the given exception and translating it into an
+ * appropriate {@link ValidationResult}, which may encapsulate details such as error messages,
+ * status codes, and specific fields that failed validation.
+ *
+ * @author edgar
+ * @since 4.5.0
+ */
+@FunctionalInterface
+public interface ValidationExceptionMapper {
+
+  /**
+   * Converts the provided exception into a {@link ValidationResult}. This method interprets the
+   * given exception, typically from a validation process, and maps it into a {@link
+   * ValidationResult} instance, encapsulating details such as validation errors and status
+   * information.
+   *
+   * @param suggestedCode the suggested status code for the validation result. Usually overriden
+   *     with {@link StatusCode#UNPROCESSABLE_ENTITY}.
+   * @param cause the exception to be mapped to a {@link ValidationResult}.
+   * @return a {@link ValidationResult} representing the mapped exception.
+   */
+  @Nullable ValidationResult toResult(StatusCode suggestedCode, Exception cause);
+}

modules/jooby-avaje-validator/src/main/java/io/jooby/avaje/validator/AvajeValidatorModule.java

@@ -21,7 +21,9 @@
 import io.jooby.Extension;
 import io.jooby.Jooby;
 import io.jooby.StatusCode;
+import io.jooby.internal.avaje.validator.ConstraintViolationMapper;
 import io.jooby.validation.BeanValidator;
+import io.jooby.validation.ValidationExceptionMapper;
 
 /**
  * Avaje Validator Module: https://jooby.io/modules/avaje-validator.
@@ -157,9 +159,13 @@ public void install(Jooby app) {
       configurer.accept(builder);
     }
 
+    var services = app.getServices();
     var validator = builder.build();
-    app.getServices().put(Validator.class, validator);
-    app.getServices().put(BeanValidator.class, new BeanValidatorImpl(validator));
+    services.put(Validator.class, validator);
+    services.put(BeanValidator.class, new BeanValidatorImpl(validator));
+    services
+        .listOf(ValidationExceptionMapper.class)
+        .add(new ConstraintViolationMapper(statusCode, title));
 
     if (!disableDefaultViolationHandler) {
       app.error(

modules/jooby-avaje-validator/src/main/java/io/jooby/avaje/validator/ConstraintViolationHandler.java

@@ -5,22 +5,15 @@
  */
 package io.jooby.avaje.validator;
 
-import static io.jooby.validation.ValidationResult.ErrorType.FIELD;
-import static io.jooby.validation.ValidationResult.ErrorType.GLOBAL;
-import static java.util.stream.Collectors.groupingBy;
-
-import java.util.ArrayList;
-import java.util.List;
-import java.util.Map;
-
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import io.avaje.validation.ConstraintViolation;
 import io.avaje.validation.ConstraintViolationException;
 import io.jooby.Context;
 import io.jooby.ErrorHandler;
 import io.jooby.StatusCode;
+import io.jooby.internal.avaje.validator.ConstraintViolationMapper;
+import io.jooby.validation.ValidationExceptionMapper;
 import io.jooby.validation.ValidationResult;
 
 /**
@@ -56,17 +49,16 @@
  * @since 3.2.10
  */
 public class ConstraintViolationHandler implements ErrorHandler {
-  private static final String ROOT_VIOLATIONS_PATH = "";
   private final Logger log = LoggerFactory.getLogger(getClass());
   private final StatusCode statusCode;
-  private final String title;
+  private final ValidationExceptionMapper mapper;
   private final boolean logException;
   private final boolean problemDetailsEnabled;
 
   public ConstraintViolationHandler(
       StatusCode statusCode, String title, boolean logException, boolean problemDetailsEnabled) {
     this.statusCode = statusCode;
-    this.title = title;
+    this.mapper = new ConstraintViolationMapper(statusCode, title);
     this.logException = logException;
     this.problemDetailsEnabled = problemDetailsEnabled;
   }
@@ -77,34 +69,11 @@ public void apply(Context ctx, Throwable cause, StatusCode code) {
       if (logException) {
         log.error(ErrorHandler.errorMessage(ctx, code), cause);
       }
-      var violations = ex.violations();
-
-      var groupedByPath = violations.stream().collect(groupingBy(ConstraintViolation::path));
-      var errors = collectErrors(groupedByPath);
-
-      var result = new ValidationResult(title, statusCode.value(), errors);
+      var result = mapper.toResult(code, ex);
       renderOrPropagate(ctx, result, code);
     }
   }
 
-  private List<ValidationResult.Error> collectErrors(
-      Map<String, List<ConstraintViolation>> groupedViolations) {
-    List<ValidationResult.Error> errors = new ArrayList<>();
-    for (var entry : groupedViolations.entrySet()) {
-      var path = entry.getKey();
-      if (ROOT_VIOLATIONS_PATH.equals(path)) {
-        errors.add(new ValidationResult.Error(null, extractMessages(entry.getValue()), GLOBAL));
-      } else {
-        errors.add(new ValidationResult.Error(path, extractMessages(entry.getValue()), FIELD));
-      }
-    }
-    return errors;
-  }
-
-  private List<String> extractMessages(List<ConstraintViolation> violations) {
-    return violations.stream().map(ConstraintViolation::message).toList();
-  }
-
   private void renderOrPropagate(Context ctx, ValidationResult result, StatusCode code) {
     if (problemDetailsEnabled) {
       ctx.getRouter().getErrorHandler().apply(ctx, result.toHttpProblem(), code);

modules/jooby-avaje-validator/src/main/java/io/jooby/internal/avaje/validator/ConstraintViolationMapper.java

@@ -0,0 +1,63 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.internal.avaje.validator;
+
+import static io.jooby.validation.ValidationResult.ErrorType.FIELD;
+import static io.jooby.validation.ValidationResult.ErrorType.GLOBAL;
+import static java.util.stream.Collectors.groupingBy;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import io.avaje.validation.ConstraintViolation;
+import io.avaje.validation.ConstraintViolationException;
+import io.jooby.StatusCode;
+import io.jooby.validation.ValidationExceptionMapper;
+import io.jooby.validation.ValidationResult;
+
+public class ConstraintViolationMapper implements ValidationExceptionMapper {
+  private static final String ROOT_VIOLATIONS_PATH = "";
+
+  private final StatusCode statusCode;
+  private final String title;
+
+  public ConstraintViolationMapper(StatusCode statusCode, String title) {
+    this.statusCode = statusCode;
+    this.title = title;
+  }
+
+  @Override
+  public ValidationResult toResult(StatusCode suggestedCode, Exception cause) {
+    if (cause instanceof ConstraintViolationException constraintViolationException) {
+      var violations = constraintViolationException.violations();
+
+      var groupedByPath = violations.stream().collect(groupingBy(ConstraintViolation::path));
+      var errors = collectErrors(groupedByPath);
+
+      return new ValidationResult(title, statusCode.value(), errors);
+    }
+    return null;
+  }
+
+  private List<ValidationResult.Error> collectErrors(
+      Map<String, List<ConstraintViolation>> groupedViolations) {
+    List<ValidationResult.Error> errors = new ArrayList<>();
+    for (var entry : groupedViolations.entrySet()) {
+      var path = entry.getKey();
+      if (ROOT_VIOLATIONS_PATH.equals(path)) {
+        errors.add(new ValidationResult.Error(null, extractMessages(entry.getValue()), GLOBAL));
+      } else {
+        errors.add(new ValidationResult.Error(path, extractMessages(entry.getValue()), FIELD));
+      }
+    }
+    return errors;
+  }
+
+  private List<String> extractMessages(List<ConstraintViolation> violations) {
+    return violations.stream().map(ConstraintViolation::message).toList();
+  }
+}

modules/jooby-avaje-validator/src/main/java/module-info.java

@@ -6,6 +6,7 @@
 /** Avaje Validator Module. */
 module io.jooby.avaje.validator {
   exports io.jooby.avaje.validator;
+  exports io.jooby.internal.avaje.validator;
 
   requires transitive io.jooby;
   requires static org.jspecify;