Merge pull request quarkusio#50730 from kevinferrare-1a/feature/unwrap-exception-always

Allow forcing exception unwrapping even when parent type mappers exist

Author: geoand

docs/src/main/asciidoc/rest.adoc

@@ -2422,6 +2422,36 @@ public class Mapper {
 
 }
 ----
+
+By default, `@UnwrapException` only unwraps exceptions when no exception mapper exists for the wrapper exception or its parent types.
+You can control the unwrapping behavior using the `strategy` attribute with one of the following values:
+
+* `ExceptionUnwrapStrategy.UNWRAP_IF_NO_MATCH` (default): Unwraps only if neither the thrown exception nor any of its supertypes have a registered mapper. Checks the entire type hierarchy before unwrapping.
+* `ExceptionUnwrapStrategy.UNWRAP_IF_NO_EXACT_MATCH`: Unwraps if the thrown exception type itself has no exact mapper registered. Checks for an exact match first, then unwraps if none is found.
+* `ExceptionUnwrapStrategy.ALWAYS`: Always unwraps exception before checking mappers. Only falls back to checking mappers for the wrapper exception if no mapper is found for any unwrapped cause.
+
+[source,java]
+----
+@UnwrapException(value = {WebApplicationException.class}, strategy = ExceptionUnwrapStrategy.UNWRAP_IF_NO_EXACT_MATCH)
+public class Mappers {
+
+    @ServerExceptionMapper
+    public Response handleRuntimeException(RuntimeException ex) {
+        // Handles RuntimeException and its subclasses
+        return Response.status(599).build();
+    }
+
+    @ServerExceptionMapper
+    public Response handleJsonProcessingException(JsonProcessingException ex) {
+        // This will be called for JsonProcessingException wrapped in WebApplicationException
+        // because UNWRAP_IF_NO_EXACT_MATCH forces unwrapping even though RuntimeException mapper that would match WebApplicationException exists
+        return Response.status(400).entity("Invalid JSON").build();
+    }
+
+}
+----
+
+This is useful when you have a general exception mapper for a parent type (like `RuntimeException`) but want to handle specific wrapped exceptions differently.
 ====
 
 [NOTE]

extensions/resteasy-reactive/rest/deployment/src/main/java/io/quarkus/resteasy/reactive/server/deployment/ResteasyReactiveScanningProcessor.java

@@ -34,6 +34,7 @@
 import org.jboss.resteasy.reactive.common.processor.ResteasyReactiveDotNames;
 import org.jboss.resteasy.reactive.common.processor.scanning.ApplicationScanningResult;
 import org.jboss.resteasy.reactive.common.processor.scanning.ResteasyReactiveInterceptorScanner;
+import org.jboss.resteasy.reactive.server.ExceptionUnwrapStrategy;
 import org.jboss.resteasy.reactive.server.UnwrapException;
 import org.jboss.resteasy.reactive.server.core.ExceptionMapping;
 import org.jboss.resteasy.reactive.server.model.ContextResolvers;
@@ -134,6 +135,9 @@ public void applicationSpecificUnwrappedExceptions(CombinedIndexBuildItem combin
         IndexView index = combinedIndexBuildItem.getIndex();
         for (AnnotationInstance instance : index.getAnnotations(UnwrapException.class)) {
             AnnotationValue value = instance.value();
+            AnnotationValue strategyValue = instance.value("strategy");
+            ExceptionUnwrapStrategy strategy = toExceptionUnwrapStrategy(strategyValue);
+
             if (value == null) {
                 // in this case we need to use the class where the annotation was placed as the exception to be unwrapped
 
@@ -162,16 +166,23 @@ public void applicationSpecificUnwrappedExceptions(CombinedIndexBuildItem combin
                                     + classInfo.name() + "'.");
                 }
 
-                producer.produce(new UnwrappedExceptionBuildItem(classInfo.name().toString()));
+                producer.produce(new UnwrappedExceptionBuildItem(classInfo.name().toString(), strategy));
             } else {
                 Type[] exceptionTypes = value.asClassArray();
                 for (Type exceptionType : exceptionTypes) {
-                    producer.produce(new UnwrappedExceptionBuildItem(exceptionType.name().toString()));
+                    producer.produce(new UnwrappedExceptionBuildItem(exceptionType.name().toString(), strategy));
                 }
             }
         }
     }
 
+    private static ExceptionUnwrapStrategy toExceptionUnwrapStrategy(AnnotationValue strategyValue) {
+        if (strategyValue != null) {
+            return ExceptionUnwrapStrategy.valueOf(strategyValue.asEnum());
+        }
+        return ExceptionUnwrapStrategy.UNWRAP_IF_NO_MATCH;
+    }
+
     @BuildStep
     public ExceptionMappersBuildItem scanForExceptionMappers(CombinedIndexBuildItem combinedIndexBuildItem,
             ApplicationResultBuildItem applicationResultBuildItem,
@@ -186,7 +197,7 @@ public ExceptionMappersBuildItem scanForExceptionMappers(CombinedIndexBuildItem
         exceptions.addBlockingProblem(BlockingOperationNotAllowedException.class);
         exceptions.addBlockingProblem(BlockingNotAllowedException.class);
         for (UnwrappedExceptionBuildItem bi : unwrappedExceptions) {
-            exceptions.addUnwrappedException(bi.getThrowableClassName());
+            exceptions.addUnwrappedException(bi.getThrowableClassName(), bi.getStrategy());
         }
         if (capabilities.isPresent(Capability.HIBERNATE_REACTIVE)) {
             exceptions.addNonBlockingProblem(

extensions/resteasy-reactive/rest/spi-deployment/src/main/java/io/quarkus/resteasy/reactive/server/spi/UnwrappedExceptionBuildItem.java

@@ -1,21 +1,35 @@
 package io.quarkus.resteasy.reactive.server.spi;
 
+import org.jboss.resteasy.reactive.server.ExceptionUnwrapStrategy;
+
 import io.quarkus.builder.item.MultiBuildItem;
 
 /**
  * When an {@link Exception} of this type is thrown and no {@code jakarta.ws.rs.ext.ExceptionMapper} exists,
  * then RESTEasy Reactive will attempt to locate an {@code ExceptionMapper} for the cause of the Exception.
+ * <p>
+ * The unwrapping behavior is controlled by the {@link ExceptionUnwrapStrategy}.
  */
 public final class UnwrappedExceptionBuildItem extends MultiBuildItem {
 
     private final String throwableClassName;
+    private final ExceptionUnwrapStrategy strategy;
 
     public UnwrappedExceptionBuildItem(String throwableClassName) {
+        this(throwableClassName, ExceptionUnwrapStrategy.UNWRAP_IF_NO_MATCH);
+    }
+
+    public UnwrappedExceptionBuildItem(String throwableClassName, ExceptionUnwrapStrategy strategy) {
         this.throwableClassName = throwableClassName;
+        this.strategy = strategy;
     }
 
     public UnwrappedExceptionBuildItem(Class<? extends Throwable> throwableClassName) {
-        this.throwableClassName = throwableClassName.getName();
+        this(throwableClassName.getName(), ExceptionUnwrapStrategy.UNWRAP_IF_NO_MATCH);
+    }
+
+    public UnwrappedExceptionBuildItem(Class<? extends Throwable> throwableClassName, ExceptionUnwrapStrategy strategy) {
+        this(throwableClassName.getName(), strategy);
     }
 
     @Deprecated(forRemoval = true)
@@ -31,4 +45,8 @@ public Class<? extends Throwable> getThrowableClass() {
     public String getThrowableClassName() {
         return throwableClassName;
     }
+
+    public ExceptionUnwrapStrategy getStrategy() {
+        return strategy;
+    }
 }

independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/ExceptionUnwrapStrategy.java

@@ -0,0 +1,24 @@
+package org.jboss.resteasy.reactive.server;
+
+/**
+ * Defines the strategy for unwrapping exceptions during exception handling.
+ */
+public enum ExceptionUnwrapStrategy {
+    /**
+     * Always unwraps exception of this type before checking mappers.
+     * Only falls back to checking mappers for the wrapper exception if no mapper is found for any unwrapped cause.
+     */
+    ALWAYS,
+
+    /**
+     * Unwraps exception only if the thrown exception type itself has no exact mapper registered.
+     * Checks for an exact match first, then unwraps if none is found.
+     */
+    UNWRAP_IF_NO_EXACT_MATCH,
+
+    /**
+     * Unwraps exceptions only if neither the thrown exception nor any of its supertypes have a registered mapper.
+     * Checks the entire type hierarchy before unwrapping.
+     */
+    UNWRAP_IF_NO_MATCH
+}

independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/UnwrapException.java

@@ -8,9 +8,36 @@
 /**
  * Used to configure that an exception (or exceptions) should be unwrapped during exception handling.
  * <p>
- * Unwrapping means that when an {@link Exception} of the configured type is thrown and no
- * {@code jakarta.ws.rs.ext.ExceptionMapper} exists,
- * then RESTEasy Reactive will attempt to locate an {@code ExceptionMapper} for the cause of the Exception.
+ * Unwrapping means that when an {@link Exception} of the configured type is thrown,
+ * RESTEasy Reactive will attempt to locate an {@code ExceptionMapper} for the cause of the Exception.
+ * <p>
+ * The unwrapping behavior is controlled by the {@link #strategy()} attribute:
+ * <ul>
+ * <li>{@link ExceptionUnwrapStrategy#ALWAYS}: Always unwraps before checking mappers. Only falls back to
+ * checking mappers for the wrapper if no mapper is found for any unwrapped cause.</li>
+ * <li>{@link ExceptionUnwrapStrategy#UNWRAP_IF_NO_EXACT_MATCH}: Unwraps only if the thrown exception type
+ * itself has no exact mapper. Checks for exact match first, then unwraps if none found.</li>
+ * <li>{@link ExceptionUnwrapStrategy#UNWRAP_IF_NO_MATCH} (default): Unwraps only if neither the thrown
+ * exception nor any of its supertypes have a registered mapper.</li>
+ * </ul>
+ * <p>
+ * Example:
+ *
+ * <pre>
+ * &#64;UnwrapException(value = { WebApplicationException.class }, strategy = ExceptionUnwrapStrategy.UNWRAP_IF_NO_EXACT_MATCH)
+ * public class ExceptionsMappers {
+ *     &#64;ServerExceptionMapper
+ *     public RestResponse&lt;Error&gt; mapUnhandledException(RuntimeException ex) {
+ *         // Handles RuntimeException and its subclasses
+ *     }
+ *
+ *     &#64;ServerExceptionMapper
+ *     public RestResponse&lt;Error&gt; mapJsonProcessingException(JsonProcessingException ex) {
+ *         // This will be called for JsonProcessingException wrapped in WebApplicationException
+ *         // because UNWRAP_IF_NO_EXACT_MATCH forces unwrapping even though RuntimeException mapper exists
+ *     }
+ * }
+ * </pre>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
@@ -20,4 +47,11 @@
      * If this is not set, the value is assumed to be the exception class where the annotation is placed
      */
     Class<? extends Exception>[] value() default {};
+
+    /**
+     * The unwrapping strategy to use for this exception.
+     * <p>
+     * Defaults to {@link ExceptionUnwrapStrategy#UNWRAP_IF_NO_MATCH}.
+     */
+    ExceptionUnwrapStrategy strategy() default ExceptionUnwrapStrategy.UNWRAP_IF_NO_MATCH;
 }

independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/core/ExceptionMapping.java

@@ -3,15 +3,14 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
-import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
-import java.util.Set;
 import java.util.function.Function;
 import java.util.function.Predicate;
 import java.util.function.Supplier;
 
 import org.jboss.resteasy.reactive.common.model.ResourceExceptionMapper;
+import org.jboss.resteasy.reactive.server.ExceptionUnwrapStrategy;
 import org.jboss.resteasy.reactive.spi.BeanFactory;
 
 @SuppressWarnings({ "unchecked", "unused" })
@@ -39,7 +38,7 @@ public class ExceptionMapping {
      */
     final List<Predicate<Throwable>> blockingProblemPredicates = new ArrayList<>();
     final List<Predicate<Throwable>> nonBlockingProblemPredicate = new ArrayList<>();
-    final Set<String> unwrappedExceptions = new HashSet<>();
+    final Map<String, ExceptionUnwrapStrategy> unwrappedExceptions = new HashMap<>();
 
     public void addBlockingProblem(Class<? extends Throwable> throwable) {
         blockingProblemPredicates.add(new ExceptionTypePredicate(throwable));
@@ -57,11 +56,11 @@ public void addNonBlockingProblem(Predicate<Throwable> predicate) {
         nonBlockingProblemPredicate.add(predicate);
     }
 
-    public void addUnwrappedException(String className) {
-        unwrappedExceptions.add(className);
+    public void addUnwrappedException(String className, ExceptionUnwrapStrategy strategy) {
+        unwrappedExceptions.put(className, strategy);
     }
 
-    public Set<String> getUnwrappedExceptions() {
+    public Map<String, ExceptionUnwrapStrategy> getUnwrappedExceptions() {
         return unwrappedExceptions;
     }